SFA API

SCADA Final Aggregator API is used to manage EVA ICS cloud and aggregated resources.

This document describes API methods for direct and JSON RPC calls. For RESTful API see SFA RESTful API.

JSON RPC 2.0 protocol is the primary EVA ICS API protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” } in the direct API). There’s no { result: “ERROR” } responses, as JSON RPC sends errors in “error” field.

If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.

Note

JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.

JSON RPC API URL:

http://<ip_address:8828>/jrpc

or

http://<ip_address:8828>

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

JSON RPC payload encoding

EVA ICS supports JSON RPC payloads, encoded as generic JSON and as MessagePack. MessagePack encoding works faster, requires less bandwidth and is highly recommended to use.

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

JSON RPC error responses

JSON RPC calls return the following error codes:

1 the item or resource is not found
2 access is denied with the set API key
6 Attempt to call undefined API method/function
10 API function failed (all errors not listed here fall within this category)
11 API function is called with invalid params
12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
14 the method is not implemented in/for requested resource

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

Warning

It’s 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). Web browser may repeat API call continuously, which may lead 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_address:8828>/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://<ip_address:8828>/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.

Direct API

Warning

Direct method calling is deprecated and scheduled to be removed (not implemented) in EVA ICS v4. Use JSON RPC API, whenever it is possible.

SFA API functions are called through URL request

http://<ip_address:8828>/sfa-api/function

If SSL is allowed in the controller configuration file, you can also use https calls.

Direct API responses

Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.

API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.

Standard responses in status/body:

200 OK { “result”: “OK” } API call completed successfully.

Standard error responses in status:

400 Bad Request Invalid request params
403 Forbidden the API key has no access to this function or resource
404 Not Found method or resource/object doesn’t exist
405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
409 Conflict resource/object already exists or is locked
500 API Error API function execution has been failed. Check input parameters and server logs.

In case API function has been failed, response body will contain JSON data with _error field, which contains error message.

{
    "_error": "unable to add object, already present",
    "result": "ERROR"
}

Contents

SFA API

Item functions

action - create unit control action

The call is considered successful when action is put into the action queue of selected unit.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 154
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "action",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey",
        "s": 1
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 154" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action", "params": {"i": "unit:tests/unit1", "k": "mykey", "s": 1}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 154" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action", "params": {"i": "unit:tests/unit1", "k": "mykey", "s": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey",
    "s": 1
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:154 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '154', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey', 's': 1}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 623
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.002784,
        "item_group": "tests",
        "item_id": "unit1",
        "item_oid": "unit:tests/unit1",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1604183929.5239828,
            "pending": 1604183929.5248153,
            "refused": 1604183929.5267668
        },
        "uuid": "f18e9f9d-2c37-427a-b54f-aa95125c417c"
    }
}

Parameters:

k valid API key
i unit id

Optionally:

s desired unit status
v desired unit value
w wait for the completion for the specified number of seconds
u action UUID (will be auto generated if none specified)
p queue priority (default is 100, lower is better)
q global queue timeout, if expires, action is marked as “dead”

Returns:

Serialized action object. If action is marked as dead, an error is returned (exception raised)

action_toggle - toggle unit status

Create unit control action to toggle its status (1->0, 0->1)

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 145
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "action_toggle",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 145" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "action_toggle", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 145" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "action_toggle", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "action_toggle",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:145 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '145', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'action_toggle', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 622
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.0027514,
        "item_group": "tests",
        "item_id": "unit1",
        "item_oid": "unit:tests/unit1",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1604183929.566067,
            "pending": 1604183929.566936,
            "refused": 1604183929.5688183
        },
        "uuid": "891646ec-69f7-4946-940b-18af3fe8c997"
    }
}

Parameters:

k valid API key
i unit id

Optionally:

w wait for the completion for the specified number of seconds
u action UUID (will be auto generated if none specified)
p queue priority (default is 100, lower is better)
q global queue timeout, if expires, action is marked as “dead”

Returns:

Serialized action object. If action is marked as dead, an error is returned (exception raised)

disable_actions - disable unit actions

Disables unit to run and queue new actions.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 147
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "disable_actions",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 147" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "disable_actions", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 147" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "disable_actions", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "disable_actions",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:147 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '147', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'disable_actions', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i unit id

enable_actions - enable unit actions

Enables unit to run and queue new actions.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 146
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "enable_actions",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 146" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "enable_actions", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 146" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "enable_actions", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "enable_actions",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:146 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '146', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'enable_actions', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i unit id

groups - get item group list

Get the list of item groups. Useful e.g. for custom interfaces.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 126
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "groups",
    "params": {
        "k": "mykey",
        "p": "unit"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 126" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "groups", "params": {"k": "mykey", "p": "unit"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 126" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "groups", "params": {"k": "mykey", "p": "unit"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "groups",
  "params": {
    "k": "mykey",
    "p": "unit"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:126 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '126', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'groups', 'params': {'k': 'mykey', 'p': 'unit'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 102
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        "clone_of_tests",
        "tests"
    ]
}

Parameters:

k valid API key
p item type (unit [U], sensor [S] or lvar [LV])

kill - kill unit actions

Apart from canceling all queued commands, this function also terminates the current running action.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "kill",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 136" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "kill", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 136" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "kill", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "kill",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'kill', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i unit id

Returns:

If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)

q_clean - clean action queue of unit

Cancels all queued actions, keeps the current action running.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 139
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "q_clean",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 139" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "q_clean", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 139" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "q_clean", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "q_clean",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:139 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '139', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'q_clean', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i unit id

result - get action status or macro run result

Checks the result of the action by its UUID or returns the actions for the specified unit or execution result of the specified macro.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 138
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "result",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 138" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "result", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 138" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "result", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "result",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:138 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '138', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'result', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 1379
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "err": "",
            "exitcode": null,
            "finished": true,
            "finished_in": 0.0049543,
            "item_group": "tests",
            "item_id": "unit1",
            "item_oid": "unit:tests/unit1",
            "item_type": "unit",
            "nstatus": 1,
            "nvalue": null,
            "out": "",
            "priority": 100,
            "status": "refused",
            "time": {
                "created": 1604184438.5920656,
                "pending": 1604184438.5939715,
                "refused": 1604184438.59702
            },
            "uuid": "c02301d3-d780-4b2e-8e06-364ecd77ad92"
        },
        {
            "err": "",
            "exitcode": null,
            "finished": true,
            "finished_in": 0.0035744,
            "item_group": "tests",
            "item_id": "unit1",
            "item_oid": "unit:tests/unit1",
            "item_type": "unit",
            "nstatus": 1,
            "nvalue": null,
            "out": "",
            "priority": 100,
            "status": "refused",
            "time": {
                "created": 1604184438.6366618,
                "pending": 1604184438.6380665,
                "refused": 1604184438.6402361
            },
            "uuid": "49870d59-955a-42d8-96a1-7ca803146f0c"
        }
    ]
}

Parameters:

k valid API key

Optionally:

u action uuid or
i unit/macro oid (either uuid or oid must be specified)
g filter by unit group
s filter by action status: Q for queued, R for running, F for finished, D for dead

Returns:

list or single serialized action object

state - get item state

State of the item or all items of the specified type can be obtained using state command.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 127
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "state",
    "params": {
        "k": "mykey",
        "p": "sensor"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 127" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "state", "params": {"k": "mykey", "p": "sensor"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 127" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "state", "params": {"k": "mykey", "p": "sensor"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "state",
  "params": {
    "k": "mykey",
    "p": "sensor"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:127 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '127', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'state', 'params': {'k': 'mykey', 'p': 'sensor'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 1556
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "controller_id": "uc/lab-ws2",
            "full_id": "clone_of_tests/sensor1",
            "group": "clone_of_tests",
            "id": "sensor1",
            "oid": "sensor:clone_of_tests/sensor1",
            "status": 0,
            "type": "sensor",
            "value": ""
        },
        {
            "controller_id": "uc/lab-ws2",
            "full_id": "clone_of_tests/sensor5",
            "group": "clone_of_tests",
            "id": "sensor5",
            "oid": "sensor:clone_of_tests/sensor5",
            "status": 0,
            "type": "sensor",
            "value": ""
        },
        {
            "controller_id": "uc/lab-ws2",
            "full_id": "clone_of_tests/t5",
            "group": "clone_of_tests",
            "id": "t5",
            "oid": "sensor:clone_of_tests/t5",
            "status": 0,
            "type": "sensor",
            "value": ""
        },
        {
            "controller_id": "uc/lab-ws2",
            "full_id": "tests/sensor1",
            "group": "tests",
            "id": "sensor1",
            "oid": "sensor:tests/sensor1",
            "status": 1,
            "type": "sensor",
            "value": "29.445"
        },
        {
            "controller_id": "uc/lab-ws2",
            "full_id": "tests/sensor5",
            "group": "tests",
            "id": "sensor5",
            "oid": "sensor:tests/sensor5",
            "status": 0,
            "type": "sensor",
            "value": ""
        }
    ]
}

Parameters:

k valid API key
p item type (unit [U], sensor [S] or lvar [LV])

Optionally:

i item id
g item group
full return full state

state_history - get item state history

State history of one item or several items of the specified type can be obtained using state_history command.

If master key is used, the method attempts to get stored state for an item even if it doesn’t present currently in system.

The method can return state log for disconnected items as well.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 149
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "state_history",
    "params": {
        "i": "sensor:env/temp_test",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 149" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "state_history", "params": {"i": "sensor:env/temp_test", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 149" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "state_history", "params": {"i": "sensor:env/temp_test", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "state_history",
  "params": {
    "i": "sensor:env/temp_test",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:149 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '149', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'state_history', 'params': {'i': 'sensor:env/temp_test', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 344
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "status": [
            1,
            1,
            1
        ],
        "t": [
            1604184434.4534957,
            1604184435.6571898,
            1604184439.1233687
        ],
        "value": [
            29.445,
            29.445,
            29.445
        ]
    }
}

Parameters:

k valid API key
a history notifier id (default: db_1)
i item oids or full ids, list or comma separated

Optionally:

s start time (timestamp or ISO or e.g. 1D for -1 day)
e end time (timestamp or ISO or e.g. 1D for -1 day)
l records limit (doesn’t work with “w”)
x state prop (“status” or “value”)
t time format (“iso” or “raw” for unix timestamp, default is “raw”)
z Time zone (pytz, e.g. UTC or Europe/Prague)
w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
g output format (“list”, “dict” or “chart”, default is “list”)
c options for chart (dict or comma separated)
o extra options for notifier data request

Returns:

history data in specified format or chart image.

For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.

Options for chart (all are optional):

type: chart type (line or bar, default is line)
tf: chart time format
out: output format (svg, png, default is svg),
style: chart style (without “Style” suffix, e.g. Dark)
other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)

If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.

Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.

If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.

state_log - get item state log

State log of a single item or group of the specified type can be obtained using state_log command.

note: only SQL notifiers are supported

Difference from state_history method:

state_log doesn’t optimize data to be displayed on charts * the data is returned from a database as-is * a single item OID or OID mask (e.g. sensor:env/#) can be specified

note: the method supports MQTT-style masks but only masks with wildcard-ending, like “type:group/subgroup/#” are supported.

The method can return state log for disconnected items as well.

For wildcard fetching, API key should have an access to the whole chosen group.

note: record limit means the limit for records, fetched from the database, but repeating state records are automatically grouped and the actual number of returned records can be lower than requested.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 143
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "state_log",
    "params": {
        "i": "sensor:tests/test1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 143" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "state_log", "params": {"i": "sensor:tests/test1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 143" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "state_log", "params": {"i": "sensor:tests/test1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "state_log",
  "params": {
    "i": "sensor:tests/test1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:143 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '143', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'state_log', 'params': {'i': 'sensor:tests/test1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 361
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295696.9975107,
            "value": 359.0
        },
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295713.5487244,
            "value": 772.0
        }
    ]
}

Parameters:

k valid API key
a history notifier id (default: db_1)
i item oid or oid mask (type:group/subgroup/#)

Optionally:

s start time (timestamp or ISO or e.g. 1D for -1 day)
e end time (timestamp or ISO or e.g. 1D for -1 day)
l records limit (doesn’t work with “w”)
t time format (“iso” or “raw” for unix timestamp, default is “raw”)
z Time zone (pytz, e.g. UTC or Europe/Prague)
o extra options for notifier data request

Returns:

state log records (list)

terminate - terminate action execution

Terminates or cancel the action if it is still queued

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 141
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "terminate",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 141" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "terminate", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 141" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "terminate", "params": {"i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "terminate",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:141 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '141', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'terminate', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
u action uuid or
i unit id

Returns:

An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)

clear - clear lvar state

set status (if expires lvar param > 0) or value (if expires isn’t set) of a logic variable to 0. Useful when lvar is used as a timer to stop it, or as a flag to set it False.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 132
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "clear",
    "params": {
        "i": "tests/lvar1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 132" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "clear", "params": {"i": "tests/lvar1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 132" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "clear", "params": {"i": "tests/lvar1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "clear",
  "params": {
    "i": "tests/lvar1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:132 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '132', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'clear', 'params': {'i': 'tests/lvar1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i lvar id

decrement - decrement lvar value

Decrement value of a logic variable. Initial value should be number

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "decrement",
    "params": {
        "i": "tests/lvar1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 136" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "decrement", "params": {"i": "tests/lvar1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 136" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "decrement", "params": {"i": "tests/lvar1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "decrement",
  "params": {
    "i": "tests/lvar1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'decrement', 'params': {'i': 'tests/lvar1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i lvar id

increment - increment lvar value

Increment value of a logic variable. Initial value should be number

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "increment",
    "params": {
        "i": "tests/lvar1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 136" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "increment", "params": {"i": "tests/lvar1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 136" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "increment", "params": {"i": "tests/lvar1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "increment",
  "params": {
    "i": "tests/lvar1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'increment', 'params': {'i': 'tests/lvar1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i lvar id

reset - reset lvar state

Set status and value of a logic variable to 1. Useful when lvar is being used as a timer to reset it, or as a flag to set it True.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 132
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "reset",
    "params": {
        "i": "tests/lvar1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 132" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "reset", "params": {"i": "tests/lvar1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 132" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "reset", "params": {"i": "tests/lvar1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "reset",
  "params": {
    "i": "tests/lvar1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:132 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '132', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'reset', 'params': {'i': 'tests/lvar1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i lvar id

set - set lvar state

Set status and value of a logic variable.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 163
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set",
    "params": {
        "i": "tests/lvar1",
        "k": "mykey",
        "s": 1,
        "v": 29
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 163" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set", "params": {"i": "tests/lvar1", "k": "mykey", "s": 1, "v": 29}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 163" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set", "params": {"i": "tests/lvar1", "k": "mykey", "s": 1, "v": 29}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set",
  "params": {
    "i": "tests/lvar1",
    "k": "mykey",
    "s": 1,
    "v": 29
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:163 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '163', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set', 'params': {'i': 'tests/lvar1', 'k': 'mykey', 's': 1, 'v': 29}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i lvar id

Optionally:

s lvar status
v lvar value

toggle - clear lvar state

set status (if expires lvar param > 0) or value (if expires isn’t set) of a logic variable to 0. Useful when lvar is used as a timer to stop it, or as a flag to set it False.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 133
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "toggle",
    "params": {
        "i": "tests/lvar1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 133" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "toggle", "params": {"i": "tests/lvar1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 133" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "toggle", "params": {"i": "tests/lvar1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "toggle",
  "params": {
    "i": "tests/lvar1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:133 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '133', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'toggle', 'params': {'i': 'tests/lvar1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k valid API key
i lvar id

Logic cycles

get_cycle - get cycle information

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 137
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_cycle",
    "params": {
        "i": "tests/cycle1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 137" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_cycle", "params": {"i": "tests/cycle1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 137" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_cycle", "params": {"i": "tests/cycle1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_cycle",
  "params": {
    "i": "tests/cycle1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:137 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '137', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_cycle', 'params': {'i': 'tests/cycle1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 368
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "controller_id": "lm/lab-ws2",
        "description": "",
        "full_id": "tests/cycle1",
        "group": "tests",
        "id": "cycle1",
        "interval": 1.0,
        "iterations": 0,
        "oid": "lcycle:tests/cycle1",
        "status": 0,
        "type": "lcycle",
        "value": null
    }
}

Parameters:

k valid API key
i cycle id

Returns:

field “value” contains real average cycle interval

groups_cycle - get cycle groups list

Get the list of cycles. Useful e.g. for custom interfaces.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 111
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "groups_cycle",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 111" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "groups_cycle", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 111" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "groups_cycle", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "groups_cycle",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:111 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '111', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'groups_cycle', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 76
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        "tests"
    ]
}

Parameters:

k valid API key

list_cycles - get cycle list

Get the list of all available cycles.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 110
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_cycles",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 110" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_cycles", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 110" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_cycles", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_cycles",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:110 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '110', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_cycles', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 432
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "controller_id": "lm/lab-ws2",
            "description": "",
            "full_id": "tests/cycle1",
            "group": "tests",
            "id": "cycle1",
            "interval": 1.0,
            "iterations": 0,
            "oid": "lcycle:tests/cycle1",
            "status": 0,
            "type": "lcycle",
            "value": null
        }
    ]
}

Parameters:

k valid API key

Optionally:

g filter by group
i filter by controller

Logic macros

groups_macro - get macro groups list

Get the list of macros. Useful e.g. for custom interfaces.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 111
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "groups_macro",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 111" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "groups_macro", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 111" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "groups_macro", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "groups_macro",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:111 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '111', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'groups_macro', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 76
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        "tests"
    ]
}

Parameters:

k valid API key

list_macros - get macro list

Get the list of all available macros.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 110
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_macros",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 110" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_macros", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 110" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_macros", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_macros",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:110 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '110', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_macros', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 355
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "action_enabled": true,
            "controller_id": "lm/lab-ws2",
            "description": "",
            "full_id": "tests/test1",
            "group": "tests",
            "id": "test1",
            "oid": "lmacro:tests/test1",
            "type": "lmacro"
        }
    ]
}

Parameters:

k valid API key

Optionally:

g filter by group
i filter by controller

run - execute macro

Execute a macro with the specified arguments.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 130
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "run",
    "params": {
        "i": "tests/test1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 130" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "run", "params": {"i": "tests/test1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 130" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "run", "params": {"i": "tests/test1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "run",
  "params": {
    "i": "tests/test1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:130 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '130', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'run', 'params': {'i': 'tests/test1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 616
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "args": [],
        "err": "",
        "exitcode": null,
        "finished": false,
        "finished_in": null,
        "item_group": "tests",
        "item_id": "test1",
        "item_oid": "lmacro:tests/test1",
        "item_type": "lmacro",
        "kwargs": {},
        "out": "",
        "priority": 100,
        "status": "queued",
        "time": {
            "created": 1604186270.96511,
            "pending": 1604186270.9661834,
            "queued": 1604186270.9684315
        },
        "uuid": "143f37f7-48ec-4062-a217-0f1c157f71fc"
    }
}

Parameters:

k valid API key
i macro id

Optionally:

a macro arguments, array or space separated
kw macro keyword arguments, name=value, comma separated or dict
w wait for the completion for the specified number of seconds
u action UUID (will be auto generated if none specified)
p queue priority (default is 100, lower is better)
q global queue timeout, if expires, action is marked as “dead”

Supervisor functions

supervisor_lock - set supervisor API lock

When supervisor lock is set, SFA API functions become read-only for all users, except users in the lock scope.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 114
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "supervisor_lock",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 114" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "supervisor_lock", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 114" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "supervisor_lock", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "supervisor_lock",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:114 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '114', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'supervisor_lock', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with allow=supervisor permissions
l lock scope (null = any supervisor can pass, u = only owner can pass, k = all users with owner’s API key can pass)
c unlock/override scope (same as lock type)
u lock user (requires master key)
p user type (null for local, “msad” for Active Directory etc.)
a lock API key ID (requires master key)

supervisor_unlock - clear supervisor API lock

API key should have permission to clear existing supervisor lock

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 116
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "supervisor_unlock",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 116" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "supervisor_unlock", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 116" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "supervisor_unlock", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "supervisor_unlock",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:116 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '116', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'supervisor_unlock', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with allow=supervisor permissions

Returns:

Successful result is returned if lock is either cleared or not set

supervisor_message - send broadcast message

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 154
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "supervisor_message",
    "params": {
        "k": "mykey",
        "m": "hello this is a test"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 154" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "supervisor_message", "params": {"k": "mykey", "m": "hello this is a test"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 154" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "supervisor_message", "params": {"k": "mykey", "m": "hello this is a test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "supervisor_message",
  "params": {
    "k": "mykey",
    "m": "hello this is a test"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:154 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '154', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'supervisor_message', 'params': {'k': 'mykey', 'm': 'hello this is a test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with allow=supervisor permissions
m message text
u message sender user (requires master key)
a message sender API key (requires master key)

Remote controllers

append_controller - connect remote controller via HTTP

Connects remote controller to the local.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 211
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "append_controller",
    "params": {
        "a": "secretkey",
        "g": "uc",
        "k": "mykey",
        "save": "true",
        "u": "localhost"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 211" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "append_controller", "params": {"a": "secretkey", "g": "uc", "k": "mykey", "save": "true", "u": "localhost"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 211" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "append_controller", "params": {"a": "secretkey", "g": "uc", "k": "mykey", "save": "true", "u": "localhost"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "append_controller",
  "params": {
    "a": "secretkey",
    "g": "uc",
    "k": "mykey",
    "save": "true",
    "u": "localhost"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:211 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '211', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'append_controller', 'params': {'a': 'secretkey', 'g': 'uc', 'k': 'mykey', 'save': 'true', 'u': 'localhost'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 624
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
        "result": {
            "build": "2019031405",
            "connected": true,
            "description": "",
            "enabled": true,
            "full_id": "uc/ws1-v1",
            "group": "uc",
            "id": "ws1-v1",
            "managed": false,
            "mqtt_update": null,
            "oid": "remote_uc:uc/ws1-v1",
            "proto": "http",
            "static": true,
            "type": "remote_uc",
            "version": "3.2.0"
        }
}

Parameters:

k API key with master permissions
u Controller API uri (proto://host:port, port not required if default)
a remote controller API key ($key to use local key)

Optionally:

m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)
s verify remote SSL certificate or pass invalid
t timeout (seconds) for the remote controller API calls
g controller type (“uc” or “lm”), autodetected if none
save save connected controller configuration on the disk immediately after creation

disable_controller - disable connected controller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 167
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "disable_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 167" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "disable_controller", "params": {"i": "uc/ws1-v1", "k": "mykey", "save": "true"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 167" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "disable_controller", "params": {"i": "uc/ws1-v1", "k": "mykey", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "disable_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:167 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '167', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'disable_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey', 'save': 'true'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id

Optionally:

save save configuration after successful call

enable_controller - enable connected controller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 166
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "enable_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 166" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "enable_controller", "params": {"i": "uc/ws1-v1", "k": "mykey", "save": "true"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 166" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "enable_controller", "params": {"i": "uc/ws1-v1", "k": "mykey", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "enable_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:166 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '166', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'enable_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey', 'save': 'true'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id

Optionally:

save save configuration after successful call

get_controller - get connected controller information

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 139
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 139" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 139" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:139 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '139', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 512
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
        "result": {
            "build": "2019031405",
            "connected": true,
            "description": "",
            "enabled": true,
            "full_id": "uc/ws1-v1",
            "group": "uc",
            "id": "ws1-v1",
            "managed": false,
            "mqtt_update": null,
            "oid": "remote_uc:uc/ws1-v1",
            "proto": "http",
            "static": true,
            "type": "remote_uc",
            "version": "3.2.0"
        }
}

Parameters:

k API key with master permissions
i controller id

list_controller_props - get controller connection parameters

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 146
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_controller_props",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 146" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_controller_props", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 146" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_controller_props", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_controller_props",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:146 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '146', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_controller_props', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 431
Content-Type: application/json
Expires: 0
Pragma: no-cache


{
    "id": 1,
    "jsonrpc": "2.0",
        "result": {
                "description": "",
                "enabled": true,
                "key": "secretkey",
                "mqtt_update": null,
                "reload_interval": 300,
                "retries": 2,
                "ssl_verify": true,
                "static": true,
                "timeout": 5.0,
                "uri": "http://localhost:8812"
            }
}

Parameters:

k API key with master permissions
i controller id

list_controllers - get controllers list

Get the list of all connected controllers.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 115
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_controllers",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 115" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_controllers", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 115" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_controllers", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_controllers",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:115 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '115', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_controllers', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 997
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "build": "2020103101",
            "connected": true,
            "description": "",
            "enabled": true,
            "full_id": "lm/lab-ws2",
            "group": "lm",
            "id": "lab-ws2",
            "managed": true,
            "mqtt_update": "eva_1",
            "oid": "remote_lm:lm/lab-ws2",
            "proto": "mqtt",
            "static": true,
            "type": "remote_lm",
            "version": "3.3.2"
        },
        {
            "build": "2020103101",
            "connected": true,
            "description": "",
            "enabled": true,
            "full_id": "uc/lab-ws2",
            "group": "uc",
            "id": "lab-ws2",
            "managed": true,
            "mqtt_update": "eva_1",
            "oid": "remote_uc:uc/lab-ws2",
            "proto": "mqtt",
            "static": true,
            "type": "remote_uc",
            "version": "3.3.2"
        }
    ]
}

Parameters:

k API key with master permissions
g filter by group (“uc” or “lm”)

list_remote - get a list of items from connected controllers

Get a list of the items loaded from the connected controllers. Useful to debug the controller connections.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_remote",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 136" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_remote", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 136" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_remote", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_remote",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_remote', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 1628
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
        "result":
            [
                {
                    "controller_id": "uc/ws1-v1",
                    "description": "",
                    "full_id": "env/temp_test",
                    "group": "env",
                    "id": "temp_test",
                    "loc_x": null,
                    "loc_y": null,
                    "loc_z": null,
                    "location": "",
                    "oid": "sensor:env/temp_test",
                    "status": 0,
                    "type": "sensor",
                    "value": "null"
                },
                {
                    "action_enabled": true,
                    "controller_id": "uc/ws1-v1",
                    "description": "",
                    "full_id": "nogroup/test2",
                    "group": "nogroup",
                    "id": "test2",
                    "loc_x": null,
                    "loc_y": null,
                    "loc_z": null,
                    "location": "",
                    "nstatus": -1,
                    "nvalue": "null",
                    "oid": "unit:nogroup/test2",
                    "status": -1,
                    "status_labels": [
                        {
                            "label": "OFF",
                            "status": 0
                        },
                        {
                            "label": "ON",
                            "status": 1
                        }
                    ],
                    "type": "unit",
                    "value": "null"
                }
            ]
}

Parameters:

k API key with master permissions

Optionally:

i controller id
g filter by item group
p filter by item type

matest_controller - test management API connection to remote controller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 142
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "matest_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 142" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "matest_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 142" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "matest_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "matest_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:142 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '142', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'matest_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id

reload_controller - reload controller

Reloads items from connected controller. If controller ID “ALL” is specified, all connected controllers are reloaded.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 142
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "reload_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 142" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "reload_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 142" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "reload_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "reload_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:142 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '142', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'reload_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id

remove_controller - disconnect controller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 142
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "remove_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 142" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "remove_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 142" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "remove_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "remove_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:142 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '142', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'remove_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id

set_controller_prop - set controller connection parameters

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 217
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_controller_prop",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey",
        "p": "reload_interval",
        "save": "true",
        "v": 60
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 217" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_controller_prop", "params": {"i": "uc/ws1-v1", "k": "mykey", "p": "reload_interval", "save": "true", "v": 60}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 217" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_controller_prop", "params": {"i": "uc/ws1-v1", "k": "mykey", "p": "reload_interval", "save": "true", "v": 60}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_controller_prop",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey",
    "p": "reload_interval",
    "save": "true",
    "v": 60
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:217 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '217', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_controller_prop', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey', 'p': 'reload_interval', 'save': 'true', 'v': 60}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id
p property name (or empty for batch set)

Optionally:

v propery value (or dict for batch set)
save save configuration after successful call

test_controller - test connection to remote controller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 140
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "test_controller",
    "params": {
        "i": "uc/ws1-v1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 140" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "test_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 140" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "test_controller", "params": {"i": "uc/ws1-v1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "test_controller",
  "params": {
    "i": "uc/ws1-v1",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:140 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '140', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'test_controller', 'params': {'i': 'uc/ws1-v1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions
i controller id

upnp_rescan_controllers - rescan controllers via UPnP

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 122
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "upnp_rescan_controllers",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 122" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "upnp_rescan_controllers", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 122" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "upnp_rescan_controllers", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "upnp_rescan_controllers",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:122 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '122', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'upnp_rescan_controllers', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions

Connected clients

notify_restart - notify connected clients about server restart

Sends a server restart event to all connected clients asking them to prepare for server restart.

All the connected clients receive the event with subject=”server” and data=”restart”. If the clients use EVA ICS JS Framework, they can catch server.restart event.

Server restart notification is sent automatically to all connected clients when the server is restarting. This API function allows to send server restart notification without actual server restart, which may be useful e.g. for testing, handling frontend restart etc.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 113
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "notify_restart",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 113" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "notify_restart", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 113" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "notify_restart", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "notify_restart",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:113 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '113', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'notify_restart', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions

reload_clients - ask connected clients to reload

Sends reload event to all connected clients asking them to reload the interface.

All the connected clients receive the event with subject=”reload” and data=”asap”. If the clients use EVA ICS JS Framework, they can catch server.reload event.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 113
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "reload_clients",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 113" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "reload_clients", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 113" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "reload_clients", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "reload_clients",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:113 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '113', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'reload_clients', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

k API key with master permissions