HMI service

The HMI service hosts web UI applications and provides HTTP/WebSocket API.

See also:

Setup

Use the template EVA_DIR/share/svc-tpl/svc-tpl-hmi.yml:

# The default HMI service
command: svc/eva-hmi
workers: 4
bus:
  path: var/bus.ipc
config:
  api:
    - proto: http
      listen: 0.0.0.0:7727
      ## if a front-end server or TLS terminator is used
      #real_ip_header: X-Real-IP
  # HMI database for API log and sessions, can be shared between instances
  # default: runtime/svc_data/<SVC_ID>/hmi.db
  #db: sqlite:///tmp/hmi.db
  #db: mysql://USER:PASSWORD@HOST/DB
  #db: postgres://USER:PASSWORD@HOST/DB
  auth_svcs:
    - eva.aaa.localauth
  session:
    timeout: 60
    prolong: true
    stick_ip: true
    allow_list_neighbors: false
  keep_api_log: 86400
  ui_path: ui
  pvt_path: pvt
  # default database service ID for item.state_log & item.state_history,
  # without eva.db. prefix, e.g. "db1" for eva.db.db1
  #default_history_db_svc: default
  mime_types: share/mime.yml
  buf_size: 16384
user: eva
timeout:
  default: 10

Create the service using eva-shell:

eva svc create eva.hmi.default /opt/eva4/share/svc-tpl/svc-tpl-hmi.yml

or using the bus CLI client:

cd /opt/eva4
cat DEPLOY.yml | ./bin/yml2mp | \
    ./sbin/bus ./var/bus.ipc rpc call eva.core svc.deploy -

(see eva.core::svc.deploy for more info)

EAPI methods

See EAPI commons for the common information about the bus, types, errors and RPC calls.

api_log.get

Description

Gets log of recent API calls

Parameters

none

Returns

List of recent API calls

Return payload example:

[
    {
        "acl": "admin",
        "auth": "token",
        "code": 0,
        "dt": "2022-05-10T03:43:26+02:00",
        "elapsed": 0.023,
        "id": "41770402-8154-4d3f-ae49-55fa9b9840b6",
        "method": "action.toggle",
        "msg": null,
        "source": "127.0.0.1",
        "t": 1652147006,
        "user": "admin"
    },
    {
        "acl": "admin",
        "auth": "token",
        "code": 0,
        "dt": "2022-05-10T03:43:32+02:00",
        "elapsed": 0.019,
        "id": "6d12a29e-ba5f-4757-a2d3-770641393dd3",
        "method": "action.toggle",
        "msg": null,
        "source": "127.0.0.1",
        "t": 1652147012,
        "user": "admin"
    }
]

i18n.cache_purge

Description

Purges i18n locale cache

Parameters

none

Returns

nothing

session.broadcast.reload

Description

Broadcasts an event to connected clients to reload interface

Parameters

none

Returns

nothing

session.broadcast.restart

Description

Broadcasts an event to connected clients that the server is restarting

Parameters

none

Returns

nothing

session.destroy

Description

Destroys an active user session

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

i

String

Session token ID

yes

session.list

Description

Lists active sessions of logged in users

Parameters

none

Returns

nothing

Return payload example:

[
    {
        "expires_in": 57,
        "id": "token:unFdcur2dGUcfA4XgBaEIVqVBFjEi83U",
        "mode": "normal",
        "source": "127.0.0.1",
        "user": "admin"
    },
    {
        "expires_in": 59,
        "id": "token:OziFA5Pzb0IndXHmVVy13Sh24BxFW73E",
        "mode": "normal",
        "source": "127.0.0.1",
        "user": "admin"
    }
]

tpl.reload

Description

Reloads server templates

Parameters

none

Returns

nothing

ws.stats

Description

Gets statistic of connected web sockets

Parameters

none

Returns

Web socket subscription statistic (struct)

Return payload example:

{
    "clients": 1,
    "sub_clients": 1,
    "subscriptions": 1
}

HTTP API

Basics

HTTP API requests are performed using JSON RPC 2.0 <https://www.jsonrpc.org/specification>.

If JSON RPC request is called without ID, it means that the server does not need to return a result. In this case, http response with a code 202 Accepted is returned.

JSON RPC API URL:

http://<IP/DOMAIN[:SVC_LISTEN_PORT]>/jrpc

or

http://<IP/DOMAIN[:SVC_LISTEN_PORT]>/

(all POST requests to the root URI are processed as JSON RPC)

EVA ICS v4 included HMI service provides a compact HTTP API, which can be extended with x calls. Administration methods can be called directly via bus calls.

JSON RPC payload encoding

Supported encodings are generic JSON and as MessagePack.

To call API methods with MessagePack-encoded payloads, use Content-Type: application/msgpack HTTP request header.

JSON RPC error responses

RPC error codes are equal to EAPI error codes.

Response field “message” may contain additional information about error.

Warning

It is highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). The web browser may repeat API call continuously considering them as timed-out, which leads to absolutely unexpected behavior.

JSON RPC via HTTP GET

Embedded equipment sometimes can send HTTP GET requests only. JSON RPC API supports such calls as well.

To make JSON RPC API request with HTTP get, send it to:

http://<IP/DOMAIN>[:SVC_LISTEN_PORT]/jrpc?i=ID&m=METHOD&p=PARAMS

where:

  • ID request ID (any custom value). If not specified, API response isn’t sent back

  • METHOD JSON RPC method to call

  • PARAMS method params, as url-encoded JSON

E.g. the following HTTP GET request will invoke method “test” with request id=1 and params { “k”: “mykey” }:

http://localhost:7727/jrpc?i=1&m=test&p=%7B%22k%22%3A%22mykey%22%7D

Note

JSON RPC API calls via HTTP GET are insecure, limited to 2048 bytes and can not be batch. Use JSON RPC via HTTP POST with JSON or MessagePack payload always when possible.

action

Description

Executes a unit action

Parameters

required

Returns

Current result payload

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Unit OID

yes

status

i16

Desired unit status

yes

value

Any

Desired unit value

no

priority

u8

Action priority

no

wait

f64

Wait max seconds to finish

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action",
  "params": {
    "i": "unit:tests/door",
    "k": "secretkey",
    "status": 1,
    "wait": 1
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action", "params": {"i": "unit:tests/door", "k": "secretkey", "status": 1, "wait": 1}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action", "params": {"i": "unit:tests/door", "k": "secretkey", "status": 1, "wait": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action",
  "params": {
    "i": "unit:tests/door",
    "k": "secretkey",
    "status": 1,
    "wait": 1
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action', 'params': {'i': 'unit:tests/door', 'k': 'secretkey', 'status': 1, 'wait': 1}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 575
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "err": null,
        "exitcode": 0,
        "finished": true,
        "node": "mws1",
        "oid": "unit:tests/door",
        "out": null,
        "params": {
            "status": 1
        },
        "priority": 100,
        "status": "completed",
        "svc": "eva.controller.virtual",
        "time": {
            "accepted": 1652391907.96199,
            "completed": 1652391907.9621937,
            "created": 1652391907.9593222
        },
        "uuid": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
    }
}

action.kill

Description

Attempts to terminate/cancel all scheduled/running actions for the specified item

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Item OID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.kill",
  "params": {
    "i": "unit:tests/door",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action.kill", "params": {"i": "unit:tests/door", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action.kill", "params": {"i": "unit:tests/door", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.kill",
  "params": {
    "i": "unit:tests/door",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action.kill', 'params': {'i': 'unit:tests/door', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

action.result

Description

Gets current action result

Parameters

required

Returns

Current result payload

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

u

String

Action UUID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.result",
  "params": {
    "k": "secretkey",
    "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action.result", "params": {"k": "secretkey", "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action.result", "params": {"k": "secretkey", "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.result",
  "params": {
    "k": "secretkey",
    "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action.result', 'params': {'k': 'secretkey', 'u': 'b37f15f0-410c-4ded-93d0-2ce744c68e08'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 575
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "err": null,
        "exitcode": 0,
        "finished": true,
        "node": "mws1",
        "oid": "unit:tests/door",
        "out": null,
        "params": {
            "status": 1
        },
        "priority": 100,
        "status": "completed",
        "svc": "eva.controller.virtual",
        "time": {
            "accepted": 1652391907.96199,
            "completed": 1652391907.9621937,
            "created": 1652391907.9593222
        },
        "uuid": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
    }
}

action.terminate

Description

Attempts to terminate/cancel an action

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

u

String

Action UUID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.terminate",
  "params": {
    "k": "secretkey",
    "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action.terminate", "params": {"k": "secretkey", "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action.terminate", "params": {"k": "secretkey", "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.terminate",
  "params": {
    "k": "secretkey",
    "u": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action.terminate', 'params': {'k': 'secretkey', 'u': 'b37f15f0-410c-4ded-93d0-2ce744c68e08'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

action.toggle

Description

Executes a unit status-toggle action

Parameters

required

Returns

Current result payload

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Unit OID

yes

priority

u8

Action priority

no

wait

f64

Wait max seconds to finish

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.toggle",
  "params": {
    "i": "unit:tests/door",
    "k": "secretkey",
    "wait": 1
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action.toggle", "params": {"i": "unit:tests/door", "k": "secretkey", "wait": 1}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action.toggle", "params": {"i": "unit:tests/door", "k": "secretkey", "wait": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action.toggle",
  "params": {
    "i": "unit:tests/door",
    "k": "secretkey",
    "wait": 1
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action.toggle', 'params': {'i': 'unit:tests/door', 'k': 'secretkey', 'wait': 1}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 575
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "err": null,
        "exitcode": 0,
        "finished": true,
        "node": "mws1",
        "oid": "unit:tests/door",
        "out": null,
        "params": {
            "status": 1
        },
        "priority": 100,
        "status": "completed",
        "svc": "eva.controller.virtual",
        "time": {
            "accepted": 1652391907.96199,
            "completed": 1652391907.9621937,
            "created": 1652391907.9593222
        },
        "uuid": "b37f15f0-410c-4ded-93d0-2ce744c68e08"
    }
}

bus::<TARGET_SVC>::<METHOD>

Description

Calls any bus method (requires admin ACL)

Parameters

Sent as-is to the target service, except “k”

Returns

The target service reply as-is

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "bus::eva.repl.1::node.get",
  "params": {
    "i": "rtest1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "bus::eva.repl.1::node.get", "params": {"i": "rtest1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "bus::eva.repl.1::node.get", "params": {"i": "rtest1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "bus::eva.repl.1::node.get",
  "params": {
    "i": "rtest1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'bus::eva.repl.1::node.get', 'params': {'i': 'rtest1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 394
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "build": 2022051001,
        "compress": true,
        "enabled": true,
        "link_uptime": 1897.710214411,
        "managed": true,
        "name": "rtest1",
        "online": true,
        "ping_interval": 1.0,
        "reload_interval": 60.0,
        "static": true,
        "timeout": 30.0,
        "version": "4.0.0"
    }
}

item.check_access

Description

Check read/write access for a single or multiple items

Parameters

required

Returns

Map OID/access

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

Vec<String>/String

Item OID(s) or masks

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.check_access",
  "params": {
    "i": "unit:tests/u1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "item.check_access", "params": {"i": "unit:tests/u1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "item.check_access", "params": {"i": "unit:tests/u1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.check_access",
  "params": {
    "i": "unit:tests/u1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'item.check_access', 'params': {'i': 'unit:tests/u1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 143
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "unit:tests/u1": {
            "r": true,
            "w": true
        }
    }
}

item.state

Description

Gets state of item(s)

Parameters

required

Returns

List of item states

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

Vec<String>/String

Item OID(s) or masks

no

full

bool

Full state (enabled + meta)

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.state",
  "params": {
    "full": true,
    "i": "sensor:#",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "item.state", "params": {"full": true, "i": "sensor:#", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "item.state", "params": {"full": true, "i": "sensor:#", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.state",
  "params": {
    "full": true,
    "i": "sensor:#",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'item.state', 'params': {'full': True, 'i': 'sensor:#', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 653
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "connected": true,
            "ieid": [
                1796,
                509854682016335
            ],
            "node": "mws1",
            "oid": "sensor:env/temp",
            "status": 1,
            "t": 1649733900.9208307,
            "value": 5
        },
        {
            "connected": true,
            "ieid": [
                2185,
                20759006408168
            ],
            "node": "mws1",
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1652387199.1481013,
            "value": 91.0
        }
    ]
}

item.state_history

Description

Gets state history for item(s)

Parameters

required

Returns

State history payload

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

Vec<String>/String

Item OID(s)

yes

t_start

f64/String

Beginning timestamp (default: last 24 hours)

no

t_end

f64/String

Ending timestamp (default: now)

no

fill

String

Fill (nS/T/H/D/W e.g. 10T for 10-minute) + optional [:precision]

no

limit

u32

Limit records to

no

xopts

Map<String, String>

Extra options, depending on database type

no

database

String

DB svc to get history from, w/o “eva.db.” pfx (def: specified in default_db)

no

output_format

String

“list” or “dict”

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.state_history",
  "params": {
    "fill": "5T:2",
    "i": "sensor:env/temp",
    "k": "secretkey",
    "t_start": 1652387700
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "item.state_history", "params": {"fill": "5T:2", "i": "sensor:env/temp", "k": "secretkey", "t_start": 1652387700}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "item.state_history", "params": {"fill": "5T:2", "i": "sensor:env/temp", "k": "secretkey", "t_start": 1652387700}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.state_history",
  "params": {
    "fill": "5T:2",
    "i": "sensor:env/temp",
    "k": "secretkey",
    "t_start": 1652387700
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'item.state_history', 'params': {'fill': '5T:2', 'i': 'sensor:env/temp', 'k': 'secretkey', 't_start': 1652387700}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 312
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "status": [
            1,
            1,
            1
        ],
        "t": [
            1652387700.0,
            1652388000.0,
            1652388300.0
        ],
        "value": [
            5,
            5,
            5
        ]
    }
}

item.state_log

Description

Gets state log for item(s)

Parameters

required

Returns

State log payload

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Item OID/Mask

yes

t_start

f64/String

Beginning timestamp (default: last 24 hours)

no

t_end/String

f64

Ending timestamp (default: now)

no

limit

u32

Limit records to

no

xopts

Map<String, String>

Extra options, depending on database type

no

database

String

DB svc to get history from, w/o “eva.db.” pfx (def: specified in default_db)

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.state_log",
  "params": {
    "i": "sensor:env/temp",
    "k": "secretkey",
    "t_start": 1652387700
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "item.state_log", "params": {"i": "sensor:env/temp", "k": "secretkey", "t_start": 1652387700}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "item.state_log", "params": {"i": "sensor:env/temp", "k": "secretkey", "t_start": 1652387700}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "item.state_log",
  "params": {
    "i": "sensor:env/temp",
    "k": "secretkey",
    "t_start": 1652387700
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'item.state_log', 'params': {'i': 'sensor:env/temp', 'k': 'secretkey', 't_start': 1652387700}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 489
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "oid": "sensor:env/temp",
            "status": 1,
            "t": 1652387838.5007,
            "value": 5
        },
        {
            "oid": "sensor:env/temp",
            "status": 1,
            "t": 1652387843.5008562,
            "value": 5
        },
        {
            "oid": "sensor:env/temp",
            "status": 1,
            "t": 1652387848.5038078,
            "value": 5
        }
    ]
}

log.get

Description

Gets memory logger log records, requires log allow in ACL

Parameters

required

Returns

List of log records

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

level

String/u8

Log level (trace, debug, info, warn, error)

no

time

u32

Recent entries, N seconds before now

no

limit

u32

Limit records to

no

module

String

Filter by module

no

rx

String

Filter by regex in message

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log.get",
  "params": {
    "k": "secretkey",
    "level": "info",
    "module": "eva::svc",
    "rx": "starting.*",
    "time": 60
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log.get", "params": {"k": "secretkey", "level": "info", "module": "eva::svc", "rx": "starting.*", "time": 60}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log.get", "params": {"k": "secretkey", "level": "info", "module": "eva::svc", "rx": "starting.*", "time": 60}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log.get",
  "params": {
    "k": "secretkey",
    "level": "info",
    "module": "eva::svc",
    "rx": "starting.*",
    "time": 60
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log.get', 'params': {'k': 'secretkey', 'level': 'info', 'module': 'eva::svc', 'rx': 'starting.*', 'time': 60}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 677
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "dt": "2022-05-12T23:06:05.965+02:00",
            "h": "mws1",
            "l": 20,
            "lvl": "info",
            "mod": "eva::svc",
            "msg": "eva.controller.eip starting puller #2, interval: 1s",
            "t": 1652389565.965001,
            "th": null
        },
        {
            "dt": "2022-05-12T23:06:05.965+02:00",
            "h": "mws1",
            "l": 20,
            "lvl": "info",
            "mod": "eva::svc",
            "msg": "eva.controller.eip starting puller #1, interval: 1s",
            "t": 1652389565.96536,
            "th": null
        }
    ]
}

login

Description

Login and obtain session token (read-write)

Parameters

required

Returns

Token information payload

  • if no params are given, the method attempts to login user using basic auth

  • if user and password are set, the method attempts to login user using the provided credentials

  • if token is set, the method returns token information

  • if both user, password and token are set, the method switches the token in read-write mode

Parameters

Name

Type

Description

Required

user

String

User login

no

password

String

User password (plain)

no

token

String

User token

no

xopts

Map<String, Any>

Extra auth ptions

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "login",
  "params": {
    "password": "secret",
    "user": "admin"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "login", "params": {"password": "secret", "user": "admin"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "login", "params": {"password": "secret", "user": "admin"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "login",
  "params": {
    "password": "secret",
    "user": "admin"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'login', 'params': {'password': 'secret', 'user': 'admin'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 194
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "acl": "admin",
        "mode": "normal",
        "token": "token:1oeb5vHbLTTABBg2DfoueSHl9kT3ZPm6",
        "user": "admin"
    }
}

logout

Description

Ends the user session and destroys the token

Parameters

required

Returns

always no error, even if the token does not exist

Parameters

Name

Type

Description

Required

token

String

User token

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "logout",
  "params": {
    "token": "token:1oeb5vHbLTTABBg2DfoueSHl9kT3ZPm6"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "logout", "params": {"token": "token:1oeb5vHbLTTABBg2DfoueSHl9kT3ZPm6"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "logout", "params": {"token": "token:1oeb5vHbLTTABBg2DfoueSHl9kT3ZPm6"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "logout",
  "params": {
    "token": "token:1oeb5vHbLTTABBg2DfoueSHl9kT3ZPm6"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'logout', 'params': {'token': 'token:1oeb5vHbLTTABBg2DfoueSHl9kT3ZPm6'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

lvar.clear

Description

Sets lvar status to 0

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lvar OID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.clear",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lvar.clear", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lvar.clear", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.clear",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lvar.clear', 'params': {'i': 'lvar:tests/v1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

lvar.decr

Description

Decrements lvar value by 1

Parameters

required

Returns

New lvar value

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lvar OID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.decr",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lvar.decr", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lvar.decr", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.decr",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lvar.decr', 'params': {'i': 'lvar:tests/v1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 55
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": 0
}

lvar.incr

Description

Increments lvar value by 1

Parameters

required

Returns

New lvar value

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lvar OID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.incr",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lvar.incr", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lvar.incr", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.incr",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lvar.incr', 'params': {'i': 'lvar:tests/v1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 55
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": 1
}

lvar.reset

Description

Sets lvar status to 1

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lvar OID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.reset",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lvar.reset", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lvar.reset", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.reset",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lvar.reset', 'params': {'i': 'lvar:tests/v1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

lvar.set

Description

Sets lvar status/value

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lvar OID

yes

status

i16

Desired status

no

value

Any

Desired value

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.set",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey",
    "status": 1,
    "value": "TEST"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lvar.set", "params": {"i": "lvar:tests/v1", "k": "secretkey", "status": 1, "value": "TEST"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lvar.set", "params": {"i": "lvar:tests/v1", "k": "secretkey", "status": 1, "value": "TEST"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.set",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey",
    "status": 1,
    "value": "TEST"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lvar.set', 'params': {'i': 'lvar:tests/v1', 'k': 'secretkey', 'status': 1, 'value': 'TEST'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

lvar.toggle

Description

Toggles lvar status between 0 and 1

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lvar OID

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.toggle",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lvar.toggle", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lvar.toggle", "params": {"i": "lvar:tests/v1", "k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lvar.toggle",
  "params": {
    "i": "lvar:tests/v1",
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lvar.toggle', 'params': {'i': 'lvar:tests/v1', 'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

run

Description

Executes a lmacro action

Parameters

required

Returns

Current result payload

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

i

String

Lmacro OID

yes

args

Vec<Any>

Arguments

yes

kwargs

Map<String, Any>

Keyword arguments

no

priority

u8

Action priority

no

wait

f64

Wait max seconds to finish

no

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "run",
  "params": {
    "i": "lmacro:tests/m1",
    "k": "secretkey",
    "kwargs": {
      "a": 123
    },
    "wait": 2
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "run", "params": {"i": "lmacro:tests/m1", "k": "secretkey", "kwargs": {"a": 123}, "wait": 2}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "run", "params": {"i": "lmacro:tests/m1", "k": "secretkey", "kwargs": {"a": 123}, "wait": 2}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "run",
  "params": {
    "i": "lmacro:tests/m1",
    "k": "secretkey",
    "kwargs": {
      "a": 123
    },
    "wait": 2
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'run', 'params': {'i': 'lmacro:tests/m1', 'k': 'secretkey', 'kwargs': {'a': 123}, 'wait': 2}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 694
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "err": null,
        "exitcode": 0,
        "finished": true,
        "node": "mws1",
        "oid": "lmacro:tests/m1",
        "out": null,
        "params": {
            "kwargs": {
                "a": 123
            }
        },
        "priority": 100,
        "status": "completed",
        "svc": "eva.controller.py",
        "time": {
            "accepted": 1652392370.5245202,
            "completed": 1652392370.524651,
            "created": 1652392370.5234292,
            "pending": 1652392370.524566,
            "running": 1652392370.524599
        },
        "uuid": "3c0354e6-dfc6-4e3e-96a4-e4f5e4471da6"
    }
}

session.list_neighbors

Description

List all logged in users (if allowed)

Parameters

required

Returns

List of logged in users

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "session.list_neighbors",
  "params": {
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "session.list_neighbors", "params": {"k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "session.list_neighbors", "params": {"k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "session.list_neighbors",
  "params": {
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'session.list_neighbors', 'params': {'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 274
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "acl": "admin",
            "mode": "normal",
            "u": "admin"
        },
        {
            "acl": "operator",
            "mode": "normal",
            "u": "operator"
        }
    ]
}

session.set_readonly

Description

Set the current session token read-only

Parameters

required

Returns

nothing

To switch back to normal (read/write) session, either call “login” method to create a new session, or call it with user+password+a params to keep the current one.

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "session.set_readonly",
  "params": {
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "session.set_readonly", "params": {"k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "session.set_readonly", "params": {"k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "session.set_readonly",
  "params": {
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'session.set_readonly', 'params': {'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 171
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "acl": "admin",
        "mode": "readonly",
        "token": "token:6SngcQsYtHSAESOzCuyJebvoAYB3ZBlp"
    }
}

set_password

Description

Changes the current password (user must be logged in and session token used)

Parameters

required

Returns

nothing

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

current_password

String

Current user’s password

yes

password

String

New user’s password

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_password",
  "params": {
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_password", "params": {"k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_password", "params": {"k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_password",
  "params": {
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_password', 'params': {'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 67
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "ok": true
  }
}

test

Description

Tests the node and HMI svc, returns system info

Parameters

required

Returns

System info (struct)

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "test",
  "params": {
    "k": "secretkey"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "test", "params": {"k": "secretkey"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "test", "params": {"k": "secretkey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "test",
  "params": {
    "k": "secretkey"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'test', 'params': {'k': 'secretkey'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 935
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "aci": {
            "acl": "admin",
            "auth": "token",
            "token_mode": "normal",
            "u": "admin"
        },
        "acl": {
            "admin": true,
            "deny": {
                "items": [],
                "pvt": [],
                "rpvt": []
            },
            "from": [
                "admin"
            ],
            "id": "admin",
            "ops": [],
            "read": {
                "items": [],
                "pvt": [],
                "rpvt": []
            },
            "write": {
                "items": []
            }
        },
        "build": 2022051001,
        "ok": true,
        "product_code": "eva4node",
        "product_name": "EVA ICS node server",
        "system_name": "mws1",
        "time": 1652312576.585399,
        "uptime": 795.01865705,
        "version": "4.0.0"
    }
}

x::<TARGET_SVC>::<METHOD>

Description

Calls “x” service method

Parameters

Sent as-is to the target service, except “k”

Returns

nothing

Allows to extend HTTP API with custom functions.

Similar to the admin bus call, but does not check ACL/permissions. The target service MUST implement “x” EAPI method and check ACL/permissions by itself.

The target service gets the following parameters payload:

Name

Type

Description

method

String

sub-method

params

Any

call params as-is, except “k”

aci

Struct

call ACI

acl

Struct

call ACL

Parameters

Name

Type

Description

Required

k

String

valid API key/token

yes

http

POST /jrpc HTTP/1.1
accept: application/json
content-type: application/json
host: localhost:7727

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "x::eva.svc.mysvc::hello",
  "params": {
    "k": "secretkey",
    "param1": "value1"
  }
}

curl

curl -i -X POST http://localhost:7727/jrpc -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "x::eva.svc.mysvc::hello", "params": {"k": "secretkey", "param1": "value1"}}'

wget

wget -S -O- http://localhost:7727/jrpc --header="Accept: application/json" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "x::eva.svc.mysvc::hello", "params": {"k": "secretkey", "param1": "value1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "x::eva.svc.mysvc::hello",
  "params": {
    "k": "secretkey",
    "param1": "value1"
  }
}' | http POST http://localhost:7727/jrpc Accept:application/json Content-Type:application/json

python-requests

requests.post('http://localhost:7727/jrpc', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'x::eva.svc.mysvc::hello', 'params': {'k': 'secretkey', 'param1': 'value1'}})

response

HTTP/1.1 200 OK
cache-control: no-cache, no-store
content-length: 64
content-type: application/json
date: Thu, 13 Aug 2021 00:00:00 GMT
expires: 0
pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": "hi there"
}

Web socket methods

Web socket method can be executed using a web socket, connected to:

ws://<IP/DOMAIN>[:SVC_LISTEN_PORT]/ws?k=TOKEN

where TOKEN is a session token.

An extra parameter buf_ttl=N can be used to ask the server to group item state events and send them in bulk. E.g. buf_ttl=0.1 can be used to receive events every 100ms.

Web socket methods provide one-way RPC calls with no returns. If a method returns a value, it means that the value is “ordered” and can be returned any time when processed.

The web socket RPC payload MUST be JSON-encoded and contains the following fields:

Field

Type

Description

Required

method

String

method name

yes

params

Any

parameters

no

Example:

{
    "method": "subscribe.state",
    "params": ["#"]
}

bye

Description

Closes the session

Parameters

none

Returns

nothing

ping

Description

Manually pings the server

Parameters

none

Returns

{s:”pong”}

subscribe.log

Description

Subscribes to log events

Parameters

u8 (20 = info, 30 = warn, 40 = error)

Returns

nothing

subscribe.state

Description

Subscribes to item state events

Parameters

Vec<OID/OIDMask(String)>

Returns

nothing

Events

After connecting, the web socket receives event payloads in the following format:

Field

Type

Description

s

String

Event subject

d

Any

Event data

The service can send events with the following subjects:

  • state a state event, data contains one or multiple (list) item states

  • pong ping-reply events, data contains nothing

  • reload reload event, the server asks clients to reload interfaces

  • server other server events, determined by data field:

    • restart server is going to be restarted soon

Note

Log events are collected from the local IPC bus. To let web sockets subscribe and receive log messages, a core bus logger MUST be configured.

The service allows subscribing to log levels info and above.