UC RESTful API

Universal Controller API is used to control and manage units and sensors

This document describes API methods for RESTful calls. For direct and JSON RPC calls look UC API.

RESTful API basics

Majority EVA ICS API components and items support REST. Parameters for POST, PUT, PATCH and DELETE requests can be sent in both JSON and multipart/form-data. For JSON, Content-Type: application/json header must be specified.

Long API calls

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.

Requests

API key can be sent in HTTP X-Auth-Key header (preferred) or in request parameters (as k).

  • GET request is used to get information about resource or list of resources of the specified type.
  • POST request is used to perform special API calls and create resources in case when resource id is generated by server. In the last case, response always contains additional field Location which points to the resource created.
  • PUT request is used to create new resources. If resource already exists, the server could refuse recreating it, responding with 409 Conflict HTTP error.
  • PATCH request is used to modify resource parameters.
  • DELETE request is used to delete resource.

For resource creation and modification, multiple parameters can be specified in a single request. For majority requests of such purpose, a special parameter “save” is used to tell server (if “save”: true) to save the resource configuration immediately after its modification.

For the group-related calls, put trailing slash at the end of the request URL:

/r/<resource_type>/<group>/

Responses

Success responses:

  • 200 OK API call completed successfully
  • 201 Created API call completed successfully, Response header Location contains either uri to the newly created object or resource is accessible by the effective request uri. For resources created with PUT, body contains either serialized resource object or resource type and id
  • 202 Accepted The server accepted command and will process it later.
  • 204 No Content API call completed successfully, no content to return

Error responses:

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

Response body may contain additional information encoded in JSON. { “result”: “OK” } and { “result”: “ERROR” } in body are not returned.

Contents

General functions

test API/key and get system info

Test can be executed with any valid API key of the controller the function is called to.

http

GET /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/core -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/core --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/core X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/core', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "acl": {
        "key_id": "masterkey",
        "master": true
    },
    "db_update": 1,
    "debug": true,
    "file_management": true,
    "layout": "enterprise",
    "polldelay": 0.001,
    "product_build": 2019031405,
    "product_code": "uc",
    "product_name": "EVA Universal Controller",
    "setup_mode": false,
    "system": "mws1-v1",
    "time": 1552867566.880533,
    "uptime": 990,
    "version": "3.2.0"
}

Parameters:

  • API Key any valid API key

Returns:

JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)

save database and runtime configuration

All modified items, their status, and configuration will be written to the disk. If exec_before_save command is defined in the controller’s configuration file, it’s called before saving and exec_after_save after (e.g. to switch the partition to write mode and back to read-only).

http

POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "save" }

curl

curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'

wget

wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'

httpie

echo '{
  "method": "save"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'save',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with sysfunc=yes permissions

execute a remote system command

Executes a command script on the server where the controller is installed.

http

POST /r/cmd/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "a": "0 2 3", "w": 5, "t": 10 }

curl

curl -i -X POST http://localhost:8812/r/cmd/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "0 2 3", "t": 10, "w": 5}'

wget

wget -S -O- http://localhost:8812/r/cmd/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "0 2 3", "t": 10, "w": 5}'

httpie

echo '{
  "a": "0 2 3",
  "t": 10,
  "w": 5
}' | http POST http://localhost:8812/r/cmd/test Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/cmd/test', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': '0 2 3',
    't': 10,
    'w': 5,
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "args": [
        "0",
        "2",
        "3"
    ],
    "cmd": "test",
    "err": "some text to stderr\n",
    "exitcode": 0,
    "out": "test script start\nparam 1: 0 ( > 0 will generate \"failed\" status)\nparam 2: 2\nparam 3: 3\ndelay 3 sec\nscript finish\n",
    "status": "completed",
    "time": {
        "completed": 1552863480.7081513,
        "created": 1552863480.6993306,
        "running": 1552863480.7001197
    },
    "timeout": 10.0
}

Parameters:

  • API Key API key with allow=cmd permissions

Optionally:

  • a string of command arguments, separated by spaces (passed to the script)
  • w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
  • t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated

shutdown the controller

Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.

http

POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "shutdown" }

curl

curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "shutdown"}'

wget

wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "shutdown"}'

httpie

echo '{
  "method": "shutdown"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'shutdown',
})

response

HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

switch debugging mode

Enables and disables debugging mode while the controller is running. After the controller is restarted, this parameter is lost and controller switches back to the mode specified in the configuration file.

http

PATCH /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "debug": true }

curl

curl -i -X PATCH http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"debug": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"debug": true}'

httpie

echo '{
  "debug": true
}' | http PATCH http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'debug': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • debug true for enabling debug mode, false for disabling

log in and get authentication token

Obtains authentication token which can be used in API calls instead of API key.

If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.

If authentication token is specified, the function will check it and return token information if it is valid.

http

POST /r/token HTTP/1.1
Host: localhost:8812
Content-Type: application/json

{ "u": "admin", "p": "123" }

curl

curl -i -X POST http://localhost:8812/r/token -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'

wget

wget -S -O- http://localhost:8812/r/token --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'

httpie

echo '{
  "p": "123",
  "u": "admin"
}' | http POST http://localhost:8812/r/token Content-Type:application/json

python-requests

requests.post('http://localhost:8812/r/token', headers={
    'Content-Type': 'application/json',
}, json={
    'p': '123',
    'u': 'admin',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "masterkey",
    "token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
    "user": "admin"
}

Parameters:

  • API Key valid API key or
  • u user login
  • p user password
  • a authentication token

Returns:

A dict, containing API key ID and authentication token

log out and purge authentication token

Purges authentication token

http

DELETE /r/token HTTP/1.1
Host: localhost:8812
X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7

curl

curl -i -X DELETE http://localhost:8812/r/token -H 'X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/token --header='X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'

httpie

http DELETE http://localhost:8812/r/token X-Auth-Key:token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7

python-requests

requests.delete('http://localhost:8812/r/token', headers={
    'X-Auth-Key': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid token

Item functions

clean action queue of unit

Cancels all queued actions, keeps the current action running.

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "q_clean" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "q_clean"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "q_clean"}'

httpie

echo '{
  "method": "q_clean"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'q_clean',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

disable unit actions

Disables unit to run and queue new actions.

http

PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "action_enabled": false }

curl

curl -i -X PATCH http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": false}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": false}'

httpie

echo '{
  "action_enabled": false
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'action_enabled': False,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

enable unit actions

Enables unit to run and queue new actions.

http

PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "action_enabled": true }

curl

curl -i -X PATCH http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": true}'

httpie

echo '{
  "action_enabled": true
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'action_enabled': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

get action status

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

http

GET /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/action -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/action --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/action X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/action', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.0006144,
        "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": 1559868829.0452583,
            "pending": 1559868829.0455182,
            "refused": 1559868829.0458727
        },
        "uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
    },
    {
        "err": "",
        "exitcode": -15,
        "finished": true,
        "finished_in": 1.301712,
        "item_group": "tests",
        "item_id": "unit3",
        "item_oid": "unit:tests/unit3",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "terminated",
        "time": {
            "created": 1559868829.0540679,
            "pending": 1559868829.054227,
            "queued": 1559868829.05472,
            "running": 1559868829.0551677,
            "terminated": 1559868830.35578
        },
        "uuid": "18bcbf97-d35d-4f18-8354-d18d092df5f7"
    },
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.0010161,
        "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": 1559868829.087297,
            "pending": 1559868829.0876813,
            "refused": 1559868829.088313
        },
        "uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
    },
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.000658,
        "item_group": "tests",
        "item_id": "unit3",
        "item_oid": "unit:tests/unit3",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1559868829.0973055,
            "pending": 1559868829.0975406,
            "refused": 1559868829.0979636
        },
        "uuid": "17570e18-03ca-4772-8665-90af574325b9"
    }
]

Parameters:

  • API Key valid API key

Optionally:

  • g filter by unit group
  • s filter by action status: Q for queued, R for running, F for finished

Returns:

list or single serialized action object

get item group list

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

http

GET /r/unit/@groups HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/unit/@groups -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/unit/@groups --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/unit/@groups X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/unit/@groups', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    "room1",
    "test_device_5",
    "test_device_7",
    "tests"
]

Parameters:

  • API Key valid API key

get item state

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

http

GET /r/sensor HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/sensor -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/sensor --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/sensor X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/sensor', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "full_id": "tests/sensor1",
        "group": "tests",
        "id": "sensor1",
        "oid": "sensor:tests/sensor1",
        "status": 1,
        "type": "sensor",
        "value": 29.445
    },
    {
        "full_id": "tests/sensor2",
        "group": "tests",
        "id": "sensor2",
        "oid": "sensor:tests/sensor2",
        "status": 1,
        "type": "sensor",
        "value": 29.445
    }
]

Parameters:

  • API Key valid API key

Optionally:

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, method attempt to get stored state for item even if it currently doesn’t present.

http

GET /r/sensor/tests/sensor2@history HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/sensor/tests/sensor2@history -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/sensor/tests/sensor2@history --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/sensor/tests/sensor2@history X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/sensor/tests/sensor2@history', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "status": [
        null,
        null,
        1,
        null,
        1
    ],
    "t": [
        1552865635.6868849,
        1552866234.5211835,
        1552866297.7497892,
        1552866495.7593722,
        1552866511.8293397,
        1552866513.8805466
    ],
    "value": [
        29.445,
        29.42,
        28,
        29.11,
        29.42,
        29.441
    ]
}

Parameters:

  • API Key valid API key
  • a history notifier id (default: db_1)

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”)
  • 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):

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.

kill unit actions

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

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "kill" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "kill"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "kill"}'

httpie

echo '{
  "method": "kill"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'kill',
})

response

HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

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)

start item maintenance mode

During maintenance mode all item updates are ignored, however actions still can be executed

http

PATCH /r/sensor/tests/sensor1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "maintenance": true }

curl

curl -i -X PATCH http://localhost:8812/r/sensor/tests/sensor1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"maintenance": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/sensor/tests/sensor1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"maintenance": true}'

httpie

echo '{
  "maintenance": true
}' | http PATCH http://localhost:8812/r/sensor/tests/sensor1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/sensor/tests/sensor1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'maintenance': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key masterkey

stop item maintenance mode

http

PATCH /r/sensor/tests/sensor1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "maintenance": false }

curl

curl -i -X PATCH http://localhost:8812/r/sensor/tests/sensor1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"maintenance": false}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/sensor/tests/sensor1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"maintenance": false}'

httpie

echo '{
  "maintenance": false
}' | http PATCH http://localhost:8812/r/sensor/tests/sensor1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/sensor/tests/sensor1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'maintenance': False,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key masterkey

terminate action execution

Terminates or cancel the action if it is still queued

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "terminate" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "terminate"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "terminate"}'

httpie

echo '{
  "method": "terminate"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'terminate',
})

response

HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

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)

toggle unit status

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

http

POST /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "i": "unit:tests/unit3", "s": "toggle" }

curl

curl -i -X POST http://localhost:8812/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": "toggle"}'

wget

wget -S -O- http://localhost:8812/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": "toggle"}'

httpie

echo '{
  "i": "unit:tests/unit3",
  "s": "toggle"
}' | http POST http://localhost:8812/r/action Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/action', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'i': 'unit:tests/unit3',
    's': 'toggle',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/17570e18-03ca-4772-8665-90af574325b9
Pragma: no-cache

{
    "err": "",
    "exitcode": null,
    "finished": true,
    "finished_in": 0.000658,
    "item_group": "tests",
    "item_id": "unit3",
    "item_oid": "unit:tests/unit3",
    "item_type": "unit",
    "nstatus": 1,
    "nvalue": null,
    "out": "",
    "priority": 100,
    "status": "refused",
    "time": {
        "created": 1559868829.0973055,
        "pending": 1559868829.0975406,
        "refused": 1559868829.0979636
    },
    "uuid": "17570e18-03ca-4772-8665-90af574325b9"
}

Parameters:

  • API Key valid API key

Optionally:

  • w wait for the completion for the specified number of seconds
  • 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)

unit control action

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

http

POST /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "s": 1, "i": "unit:tests/unit3", "s": 1 }

curl

curl -i -X POST http://localhost:8812/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": 1}'

wget

wget -S -O- http://localhost:8812/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": 1}'

httpie

echo '{
  "i": "unit:tests/unit3",
  "s": 1
}' | http POST http://localhost:8812/r/action Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/action', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'i': 'unit:tests/unit3',
    's': 1,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/18bcbf97-d35d-4f18-8354-d18d092df5f7
Pragma: no-cache

{
    "err": "",
    "exitcode": null,
    "finished": false,
    "finished_in": null,
    "item_group": "tests",
    "item_id": "unit3",
    "item_oid": "unit:tests/unit3",
    "item_type": "unit",
    "nstatus": 1,
    "nvalue": null,
    "out": "",
    "priority": 100,
    "status": "running",
    "time": {
        "created": 1559868829.0540679,
        "pending": 1559868829.054227,
        "queued": 1559868829.05472,
        "running": 1559868829.0551677
    },
    "uuid": "18bcbf97-d35d-4f18-8354-d18d092df5f7"
}

Parameters:

  • API Key valid API key

Optionally:

  • s desired unit status
  • v desired unit value
  • w wait for the completion for the specified number of seconds
  • 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)

update the status and value of the item

Updates the status and value of the item. This is one of the ways of passive state update, for example with the use of an external controller.

Note

Calling without s and v params will force item to perform passive update requesting its status from update script or driver.

http

POST /r/sensor/tests/sensor2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "s": 1, "v": 29.445 }

curl

curl -i -X POST http://localhost:8812/r/sensor/tests/sensor2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": 1, "v": 29.445}'

wget

wget -S -O- http://localhost:8812/r/sensor/tests/sensor2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": 1, "v": 29.445}'

httpie

echo '{
  "s": 1,
  "v": 29.445
}' | http POST http://localhost:8812/r/sensor/tests/sensor2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/sensor/tests/sensor2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    's': 1,
    'v': 29.445,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

Optionally:

  • s item status
  • v item value

Item management

list items

Parameters:

  • API Key API key with master permissions

Optionally:

  • x serialize specified item prop(s)

Returns:

the list of all item available

create multi-update

Creates new multi-update.

http

PUT /r/mu/tests/mu2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "update_timeout": 10, "update_interval": 5 }

curl

curl -i -X PUT http://localhost:8812/r/mu/tests/mu2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "update_interval": 5, "update_timeout": 10}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/mu/tests/mu2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "update_interval": 5, "update_timeout": 10}'

httpie

echo '{
  "save": true,
  "update_interval": 5,
  "update_timeout": 10
}' | http PUT http://localhost:8812/r/mu/tests/mu2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/mu/tests/mu2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'save': True,
    'update_interval': 5,
    'update_timeout': 10,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "config_changed": false,
    "description": "",
    "full_id": "tests/mu2",
    "group": "tests",
    "id": "mu2",
    "oid": "mu:tests/mu2",
    "status": 0,
    "type": "mu",
    "value": "null",
    "virtual": false
}

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save multi-update configuration immediately

create new item

Creates new item.

http

PUT /r/sensor/tests/sensor2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "update_timeout": 10, "update_interval": 5 }

curl

curl -i -X PUT http://localhost:8812/r/sensor/tests/sensor2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "update_interval": 5, "update_timeout": 10}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/sensor/tests/sensor2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "update_interval": 5, "update_timeout": 10}'

httpie

echo '{
  "save": true,
  "update_interval": 5,
  "update_timeout": 10
}' | http PUT http://localhost:8812/r/sensor/tests/sensor2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/sensor/tests/sensor2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'save': True,
    'update_interval': 5,
    'update_timeout': 10,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "config_changed": false,
    "description": "",
    "full_id": "tests/sensor2",
    "group": "tests",
    "id": "sensor2",
    "loc_x": null,
    "loc_y": null,
    "loc_z": null,
    "location": "",
    "oid": "sensor:tests/sensor2",
    "status": 0,
    "type": "sensor",
    "value": "null",
    "virtual": false
}

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save multi-update configuration immediately

create new sensor

Creates new sensor.

http

PUT /r/sensor/tests/sensor7 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "update_timeout": 10, "update_interval": 5 }

curl

curl -i -X PUT http://localhost:8812/r/sensor/tests/sensor7 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "update_interval": 5, "update_timeout": 10}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/sensor/tests/sensor7 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "update_interval": 5, "update_timeout": 10}'

httpie

echo '{
  "save": true,
  "update_interval": 5,
  "update_timeout": 10
}' | http PUT http://localhost:8812/r/sensor/tests/sensor7 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/sensor/tests/sensor7', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'save': True,
    'update_interval': 5,
    'update_timeout': 10,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "config_changed": false,
    "description": "",
    "full_id": "tests/sensor7",
    "group": "tests",
    "id": "sensor7",
    "loc_x": null,
    "loc_y": null,
    "loc_z": null,
    "location": "",
    "oid": "sensor:tests/sensor7",
    "status": 0,
    "type": "sensor",
    "value": "null",
    "virtual": false
}

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save sensor configuration immediately

create new unit

Creates new unit.

http

PUT /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "update_timeout": 10, "action_enabled": true }

curl

curl -i -X PUT http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": true, "save": true, "update_timeout": 10}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": true, "save": true, "update_timeout": 10}'

httpie

echo '{
  "action_enabled": true,
  "save": true,
  "update_timeout": 10
}' | http PUT http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'action_enabled': True,
    'save': True,
    'update_timeout': 10,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "action_enabled": true,
    "config_changed": false,
    "description": "",
    "full_id": "tests/unit3",
    "group": "tests",
    "id": "unit3",
    "loc_x": null,
    "loc_y": null,
    "loc_z": null,
    "location": "",
    "nstatus": 0,
    "nvalue": "null",
    "oid": "unit:tests/unit3",
    "status": 0,
    "status_labels": [
        {
            "label": "OFF",
            "status": 0
        },
        {
            "label": "ON",
            "status": 1
        }
    ],
    "type": "unit",
    "value": "null",
    "virtual": false
}

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save unit configuration immediately

delete item or group

Deletes the item or the group (and all the items in it) from the system.

http

DELETE /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/unit/tests/unit3 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/unit/tests/unit3 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/unit/tests/unit3 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/unit/tests/unit3', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get item configuration

http

GET /r/unit/tests/unit3@config HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/unit/tests/unit3@config -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit3@config --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/unit/tests/unit3@config X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/unit/tests/unit3@config', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "action_enabled": true,
    "full_id": "tests/unit3",
    "group": "tests",
    "id": "unit3",
    "oid": "unit:tests/unit3",
    "type": "unit",
    "update_timeout": 10.0
}

Parameters:

  • API Key API key with master permissions

Returns:

complete item configuration

list item properties

Get all editable parameters of the item confiugration.

http

GET /r/unit/tests/unit1@props HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/unit/tests/unit1@props -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit1@props --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/unit/tests/unit1@props X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/unit/tests/unit1@props', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "action_allow_termination": false,
    "action_always_exec": false,
    "action_driver_config": null,
    "action_enabled": true,
    "action_exec": null,
    "action_queue": 0,
    "action_timeout": null,
    "auto_off": 0,
    "description": "",
    "expires": 0,
    "location": null,
    "mqtt_control": null,
    "mqtt_update": null,
    "snmp_trap": null,
    "status_labels": {
        "0": "OFF",
        "1": "ON"
    },
    "term_kill_interval": null,
    "update_delay": 0,
    "update_driver_config": null,
    "update_exec": null,
    "update_exec_after_action": false,
    "update_if_action": false,
    "update_interval": 0,
    "update_state_after_action": true,
    "update_timeout": null,
    "virtual": false
}

Parameters:

  • API Key API key with master permissions

save item configuration

Saves item. configuration on disk (even if it hasn’t been changed)

http

POST /r/unit/tests/unit1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "save" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/unit1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'

httpie

echo '{
  "method": "save"
}' | http POST http://localhost:8812/r/unit/tests/unit1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/unit1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'save',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

set item property

Set configuration parameters of the item.

http

PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "action_allow_termination": true, "action_timeout": 10, "update_interval": 10 }

curl

curl -i -X PATCH http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_allow_termination": true, "action_timeout": 10, "update_interval": 10}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_allow_termination": true, "action_timeout": 10, "update_interval": 10}'

httpie

echo '{
  "action_allow_termination": true,
  "action_timeout": 10,
  "update_interval": 10
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'action_allow_termination': True,
    'action_timeout': 10,
    'update_interval': 10,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

clone group

Creates a copy of all items from the group.

http

POST /r/unit/tests/ HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "clone", "n": "clone_tests" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/ -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "clone", "n": "clone_tests"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/ --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "clone", "n": "clone_tests"}'

httpie

echo '{
  "method": "clone",
  "n": "clone_tests"
}' | http POST http://localhost:8812/r/unit/tests/ Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'clone',
    'n': 'clone_tests',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • n new group to clone to

Optionally:

  • p item ID prefix, e.g. device1. for device1.temp1, device1.fan1
  • r iem ID prefix in the new group, e.g. device2 (both prefixes must be specified)
  • save save configuration immediately

clone item

Creates a copy of the item.

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "clone", "n": "tests/clone_of_unit3" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "clone", "n": "tests/clone_of_unit3"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "clone", "n": "tests/clone_of_unit3"}'

httpie

echo '{
  "method": "clone",
  "n": "tests/clone_of_unit3"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'clone',
    'n': 'tests/clone_of_unit3',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "action_enabled": true,
    "full_id": "tests/clone_of_unit3",
    "group": "tests",
    "id": "clone_of_unit3",
    "nstatus": 0,
    "nvalue": "null",
    "oid": "unit:tests/clone_of_unit3",
    "status": 0,
    "type": "unit",
    "value": "null"
}

Parameters:

  • API Key API key with master permissions
  • n new item id

Optionally:

  • save save multi-update configuration immediately

1-Wire bus via OWFS

create OWFS bus

Creates (defines) OWFS bus with the specified configuration.

Parameter “location” (“n”) should contain the connection configuration, e.g. “localhost:4304” for owhttpd or “i2c=/dev/i2c-1:ALL”, “/dev/i2c-0 –w1” for local 1-Wire bus via I2C, depending on type.

http

PUT /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "n": "localhost:4304", "l": true, "t": 1, "r": 5, "d": 0.3, "save": true }

curl

curl -i -X PUT http://localhost:8812/r/owfs/bus1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"d": 0.3, "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/owfs/bus1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"d": 0.3, "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'

httpie

echo '{
  "d": 0.3,
  "l": true,
  "n": "localhost:4304",
  "r": 5,
  "save": true,
  "t": 1
}' | http PUT http://localhost:8812/r/owfs/bus1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/owfs/bus1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'd': 0.3,
    'l': True,
    'n': 'localhost:4304',
    'r': 5,
    'save': True,
    't': 1,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "delay": 0.3,
    "id": "bus1",
    "location": "localhost:4304",
    "lock": true,
    "retries": 5,
    "timeout": 1.0
}

Parameters:

  • API Key API key with master permissions
  • n OWFS location

Optionally:

  • l lock port on operations, which means to wait while OWFS bus is used by other controller thread (driver command)
  • t OWFS operations timeout (in seconds, default: default timeout)
  • r retry attempts for each operation (default: no retries)
  • d delay between bus operations (default: 50ms)
  • save save OWFS bus config after creation

Returns:

If bus with the selected ID is already defined, error is not returned and bus is recreated.

delete OWFS bus

Deletes (undefines) OWFS bus.

Note

In some cases deleted OWFS bus located on I2C may lock libow library calls, which require controller restart until you can use (create) the same I2C bus again.

http

DELETE /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/owfs/bus1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/owfs/bus1 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/owfs/bus1 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/owfs/bus1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get OWFS bus configuration

http

GET /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/owfs/bus1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/owfs/bus1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/owfs/bus1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/owfs/bus1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "delay": 0.3,
    "id": "bus1",
    "location": "localhost:4304",
    "lock": true,
    "retries": 5,
    "timeout": 1.0
}

Parameters:

  • API Key API key with master permissions

list OWFS buses

http

GET /r/owfs HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/owfs -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/owfs --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/owfs X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/owfs', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "delay": 0.3,
        "id": "bus1",
        "location": "localhost:4304",
        "lock": true,
        "retries": 5,
        "timeout": 1.0
    },
    {
        "delay": 0.3,
        "id": "bus_local",
        "location": "localhost:4304",
        "lock": true,
        "retries": 5,
        "timeout": 1.0
    },
    {
        "delay": 0.05,
        "id": "bus_local1",
        "location": "localhost:4304",
        "lock": false,
        "retries": 0,
        "timeout": 4.0
    },
    {
        "delay": 0.05,
        "id": "test",
        "location": "localhost:4304",
        "lock": true,
        "retries": 0,
        "timeout": 4.0
    }
]

Parameters:

  • API Key API key with master permissions

scan OWFS bus

Scan OWFS bus for connected 1-Wire devices.

http

POST /r/owfs/bus_local HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "scan" }

curl

curl -i -X POST http://localhost:8812/r/owfs/bus_local -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "scan"}'

wget

wget -S -O- http://localhost:8812/r/owfs/bus_local --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "scan"}'

httpie

echo '{
  "method": "scan"
}' | http POST http://localhost:8812/r/owfs/bus_local Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/owfs/bus_local', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'scan',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "path": "22.765A2E63339F",
        "type": "DS1822"
    },
    {
        "path": "28.4AEC29CDBAAB",
        "type": "DS18B20"
    },
    {
        "path": "10.67C6697351FF",
        "type": "DS18S20"
    },
    {
        "path": "05.F2FBE3467CC2",
        "type": "DS2405"
    },
    {
        "path": "29.54F81BE8E78D",
        "type": "DS2408"
    }
]

Parameters:

  • API Key API key with master permissions

Optionally:

  • p specified equipment type (e.g. DS18S20,DS2405), list or comma separated
  • a Equipment attributes (e.g. temperature, PIO), list comma separated
  • n Equipment path
  • has_all Equipment should have all specified attributes
  • full obtain all attributes plus values

Returns:

If both “a” and “full” args are specified. the function will examine and values of attributes specified in “a” param. (This will poll “released” bus, even if locking is set up, so be careful with this feature in production environment).

Bus acquire error can be caused in 2 cases:

  • bus is locked * owfs resource not initialized (libow or location problem)

test OWFS bus

Verifies OWFS bus checking library initialization status.

http

POST /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "test" }

curl

curl -i -X POST http://localhost:8812/r/owfs/bus1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'

wget

wget -S -O- http://localhost:8812/r/owfs/bus1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'

httpie

echo '{
  "method": "test"
}' | http POST http://localhost:8812/r/owfs/bus1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/owfs/bus1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'test',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Modbus ports

create virtual Modbus port

Creates virtual Modbus port with the specified configuration.

Modbus params should contain the configuration of hardware Modbus port. The following hardware port types are supported:

  • tcp , udp Modbus protocol implementations for TCP/IP networks. The params should be specified as: <protocol>:<host>[:port], e.g. tcp:192.168.11.11:502
  • rtu, ascii, binary Modbus protocol implementations for the local bus connected with USB or serial port. The params should be specified as: <protocol>:<device>:<speed>:<data>:<parity>:<stop> e.g. rtu:/dev/ttyS0:9600:8:E:1

http

PUT /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "p": "udp:192.168.33.33:502", "l": true, "t": 0.5, "r": 3, "d": 0.2, "save": true }

curl

curl -i -X PUT http://localhost:8812/r/modbus/mbp2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"d": 0.2, "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/modbus/mbp2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"d": 0.2, "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'

httpie

echo '{
  "d": 0.2,
  "l": true,
  "p": "udp:192.168.33.33:502",
  "r": 3,
  "save": true,
  "t": 0.5
}' | http PUT http://localhost:8812/r/modbus/mbp2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/modbus/mbp2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'd': 0.2,
    'l': True,
    'p': 'udp:192.168.33.33:502',
    'r': 3,
    'save': True,
    't': 0.5,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "delay": 0.2,
    "id": "mbp2",
    "lock": true,
    "params": "udp:192.168.33.33:502",
    "retries": 3,
    "timeout": 0.5
}

Parameters:

  • API Key API key with master permissions
  • p Modbus params

Optionally:

  • l lock port on operations, which means to wait while Modbus port is used by other controller thread (driver command)
  • t Modbus operations timeout (in seconds, default: default timeout)
  • r retry attempts for each operation (default: no retries)
  • d delay between virtual port operations (default: 20ms)
  • save save Modbus port config after creation

Returns:

If port with the selected ID is already created, error is not returned and port is recreated.

delete virtual Modbus port

Deletes virtual Modbus port.

http

DELETE /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/modbus/mbp2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/modbus/mbp2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/modbus/mbp2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/modbus/mbp2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get virtual Modbus port configuration

http

GET /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/modbus/mbp2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/modbus/mbp2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/modbus/mbp2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/modbus/mbp2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "delay": 0.2,
    "id": "mbp2",
    "lock": true,
    "params": "udp:192.168.33.33:502",
    "retries": 3,
    "timeout": 0.5
}

Parameters:

  • API Key API key with master permissions

list virtual Modbus ports

http

GET /r/modbus HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/modbus -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/modbus --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/modbus X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/modbus', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "delay": 0.2,
        "id": "mbp1",
        "lock": true,
        "params": "udp:192.168.33.33:502",
        "retries": 3,
        "timeout": 0.5
    },
    {
        "delay": 0.2,
        "id": "mbp2",
        "lock": true,
        "params": "udp:192.168.33.33:502",
        "retries": 3,
        "timeout": 0.5
    },
    {
        "delay": 0.02,
        "id": "test",
        "lock": false,
        "params": "tcp:192.168.1.1",
        "retries": 0,
        "timeout": 4.0
    }
]

Parameters:

  • API Key API key with master permissions

read Modbus register(s) from remote slave

Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).

Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15

http

GET /r/modbus/local/1/h10-12,c5-6 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/modbus/local/1/h10-12,c5-6 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/modbus/local/1/h10-12,c5-6 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/modbus/local/1/h10-12,c5-6 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/modbus/local/1/h10-12,c5-6', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "addr": "c5",
        "value": 0
    },
    {
        "addr": "c6",
        "value": 0
    },
    {
        "addr": "h10",
        "value": 25
    },
    {
        "addr": "h11",
        "value": 0
    },
    {
        "addr": "h12",
        "value": 0
    }
]

Parameters:

  • API Key API key with master permissions

Optionally:

  • t max allowed timeout for the operation

test virtual Modbus port

Verifies virtual Modbus port by calling connect() Modbus client method.

Note

As Modbus UDP doesn’t require a port to be connected, API call always returns success unless the port is locked.

http

POST /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "test" }

curl

curl -i -X POST http://localhost:8812/r/modbus/mbp2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'

wget

wget -S -O- http://localhost:8812/r/modbus/mbp2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'

httpie

echo '{
  "method": "test"
}' | http POST http://localhost:8812/r/modbus/mbp2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/modbus/mbp2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'test',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

write Modbus register(s) to remote slave

Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, c - coil).

http

PUT /r/modbus/local/1/h10 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "v": 2522 }

curl

curl -i -X PUT http://localhost:8812/r/modbus/local/1/h10 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": 2522}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/modbus/local/1/h10 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": 2522}'

httpie

echo '{
  "v": 2522
}' | http PUT http://localhost:8812/r/modbus/local/1/h10 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/modbus/local/1/h10', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'v': 2522,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • v register value(s) (integer or hex or list)
  • z if True, use 0x05-06 commands (write single register/coil)

Optionally:

  • t max allowed timeout for the operation

get Modbus slave data

Get data from Modbus slave memory space

Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).

Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15

http

GET /r/modbus-slave/h1000-1005,c10-15 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/modbus-slave/h1000-1005,c10-15', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "addr": "c10",
        "value": 0
    },
    {
        "addr": "c11",
        "value": 0
    },
    {
        "addr": "c12",
        "value": 0
    },
    {
        "addr": "c13",
        "value": 0
    },
    {
        "addr": "c14",
        "value": 0
    },
    {
        "addr": "c15",
        "value": 0
    },
    {
        "addr": "h1000",
        "value": 0
    },
    {
        "addr": "h1001",
        "value": 0
    },
    {
        "addr": "h1002",
        "value": 0
    },
    {
        "addr": "h1003",
        "value": 0
    },
    {
        "addr": "h1004",
        "value": 0
    },
    {
        "addr": "h1005",
        "value": 0
    }
]

Parameters:

  • API Key API key with master permissions

Physical interfaces (PHIs)

delete PHI module file

Deletes PHI module file, if the module is loaded, all its instances should be unloaded first.

http

DELETE /r/phi-module/gpio_power HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/phi-module/gpio_power -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/phi-module/gpio_power --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/phi-module/gpio_power X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/phi-module/gpio_power', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

discover installed equipment supported by PHI module

http

GET /r/phi-module/nanoleaf@discover HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/phi-module/nanoleaf@discover -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/phi-module/nanoleaf@discover --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/phi-module/nanoleaf@discover X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/phi-module/nanoleaf@discover', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Content-Type: application/json
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Length: 411

[
    {
        "!opt": "cols",
        "value": [
            "IP",
            "Name"
        ]
    },
    {
        "!load": {
            "host": "192.168.25.81"
        },
        "IP": "192.168.25.81",
        "Name": "Nanoleaf Light Panels 54:e2:31"
    },
    {
        "!load": {
            "host": "10.90.1.82"
        },
        "IP": "10.90.1.82",
        "Name": "Nanoleaf Light Panels 54:f2:36"
    }
]

Parameters:

  • API Key API key with master permissions

Optionally:

  • x interface to perform discover on
  • w max time for the operation

execute additional PHI commands

Execute PHI command and return execution result (as-is). help command returns all available commands.

http

POST /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "c": "update_firmware", "a": "/opt/firmware/fw.dat", "method": "exec" }

curl

curl -i -X POST http://localhost:8812/r/phi/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "method": "exec"}'

wget

wget -S -O- http://localhost:8812/r/phi/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "method": "exec"}'

httpie

echo '{
  "a": "/opt/firmware/fw.dat",
  "c": "update_firmware",
  "method": "exec"
}' | http POST http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/phi/test1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': '/opt/firmware/fw.dat',
    'c': 'update_firmware',
    'method': 'exec',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "output": "not implemented"
}

Parameters:

  • API Key API key with master permissions
  • c command to exec
  • a command argument

get PHI module info

http

GET /r/phi-module/vrtrelay HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/phi-module/vrtrelay -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/phi-module/vrtrelay --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/phi-module/vrtrelay X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/phi-module/vrtrelay', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "api": 1,
    "author": "Altertech Group, https://www.altertech.com/",
    "description": "Emulates 16-port relay",
    "equipment": [
        "virtual"
    ],
    "features": [
        "port_get",
        "port_set",
        "aao_set",
        "aao_get"
    ],
    "help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
    "license": "Apache License 2.0",
    "lpi_default": "basic",
    "mod": "vrtrelay",
    "mods_required": [],
    "oid": null,
    "required": [
        "port_get",
        "port_set"
    ],
    "version": "1.0.1"
}

Parameters:

  • API Key API key with master permissions

get PHI usage help

http

GET /r/phi-module/vrtrelay?help=cfg HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' -H 'X-Auth-Key: mykey'

wget

wget -S -O- 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' --header='X-Auth-Key: mykey'

httpie

http 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/phi-module/vrtrelay?help=cfg', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "help": "ports status on load (default: -1)",
        "name": "default_status",
        "required": false,
        "type": "int"
    },
    {
        "help": "send updates to items every N sec",
        "name": "update",
        "required": false,
        "type": "float"
    }
]

Parameters:

  • API Key API key with master permissions

get list of PHI ports

http

GET /r/phi/test1@ports HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/phi/test1@ports -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/phi/test1@ports --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/phi/test1@ports X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/phi/test1@ports', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "description": "virtual relay port #1",
        "name": "port #1",
        "port": "1"
    },
    {
        "description": "virtual relay port #2",
        "name": "port #2",
        "port": "2"
    },
    {
        "description": "virtual relay port #3",
        "name": "port #3",
        "port": "3"
    },
    {
        "description": "virtual relay port #4",
        "name": "port #4",
        "port": "4"
    },
    {
        "description": "virtual relay port #5",
        "name": "port #5",
        "port": "5"
    },
    {
        "description": "virtual relay port #6",
        "name": "port #6",
        "port": "6"
    },
    {
        "description": "virtual relay port #7",
        "name": "port #7",
        "port": "7"
    },
    {
        "description": "virtual relay port #8",
        "name": "port #8",
        "port": "8"
    },
    {
        "description": "virtual relay port #9",
        "name": "port #9",
        "port": "9"
    },
    {
        "description": "virtual relay port #10",
        "name": "port #10",
        "port": "10"
    },
    {
        "description": "virtual relay port #11",
        "name": "port #11",
        "port": "11"
    },
    {
        "description": "virtual relay port #12",
        "name": "port #12",
        "port": "12"
    },
    {
        "description": "virtual relay port #13",
        "name": "port #13",
        "port": "13"
    },
    {
        "description": "virtual relay port #14",
        "name": "port #14",
        "port": "14"
    },
    {
        "description": "virtual relay port #15",
        "name": "port #15",
        "port": "15"
    },
    {
        "description": "virtual relay port #16",
        "name": "port #16",
        "port": "16"
    }
]

Parameters:

  • API Key API key with master permissions

get list of available PHI modules

http

GET /r/phi-module HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/phi-module -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/phi-module --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/phi-module X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/phi-module', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "api": 1,
        "author": "Altertech Group, https://www.altertech.com/",
        "description": "EG-PM2-LAN smart PDU",
        "equipment": [
            "EG-PM2-LAN"
        ],
        "features": [
            "aao_get",
            "port_set",
            "cache"
        ],
        "help": "\nPHI for Energenie (Gembird) EG-PM2-LAN smart PDU. You may use 'skip_logout'\nparam to let PHI skip logout procedure after the requests. This speed up the\nfunctions however may cause the equipment to be locked to UC IP only.\n",
        "id": null,
        "license": "https://www.eva-ics.com/license",
        "lpi_default": "basic",
        "mod": "eg_pm2lan",
        "mods_required": [],
        "oid": null,
        "required": [
            "aao_get",
            "port_set",
            "status",
            "action"
        ],
        "version": "1.0.2"
    },
    {
        "api": 3,
        "author": "Altertech Group, https://www.altertech.com/",
        "description": "1-Wire OWFS universal sensor driver",
        "equipment": [
            "Any 1-Wire sensor"
        ],
        "features": [
            "port_get",
            "universal"
        ],
        "help": "\nPHI for Maxim Integrated 1-Wire DS18N20 equipment working via OWFS.\n\nCan be used for various types of sensors as attr (e.g. \"temperature\" or\n\"voltage\") is specified by user. This is unversal PHI, owfs bus, path and attr\ncan be specified in EVA ICS sensor configuration.\n",
        "id": null,
        "license": "Apache License 2.0",
        "lpi_default": "sensor",
        "mod": "ow_sensor",
        "mods_required": [],
        "oid": null,
        "required": [
            "port_get",
            "value"
        ],
        "version": "1.0.0"
    }
]

Parameters:

  • API Key API key with master permissions

list loaded PHIs

http

GET /r/phi HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/phi -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/phi --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/phi X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/phi', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "id": "test",
        "mod": "vrtrelay"
    },
    {
        "id": "test1",
        "mod": "vrtrelay"
    },
    {
        "id": "test2",
        "mod": "vrtrelay"
    }
]

Parameters:

  • API Key API key with master permissions
  • full get exntended information

load PHI module

Loads Physical Interface.

http

PUT /r/phi/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "m": "vrtrelay", "c": "default_status=0", "save": true }

curl

curl -i -X PUT http://localhost:8812/r/phi/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "default_status=0", "m": "vrtrelay", "save": true}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/phi/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"c": "default_status=0", "m": "vrtrelay", "save": true}'

httpie

echo '{
  "c": "default_status=0",
  "m": "vrtrelay",
  "save": true
}' | http PUT http://localhost:8812/r/phi/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/phi/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': 'default_status=0',
    'm': 'vrtrelay',
    'save': True,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "api": 1,
    "author": "Altertech Group, https://www.altertech.com/",
    "cfg": {
        "default_status": 0
    },
    "description": "Emulates 16-port relay",
    "equipment": [
        "virtual"
    ],
    "features": [
        "port_get",
        "port_set",
        "aao_set",
        "aao_get"
    ],
    "help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
    "id": "test2",
    "license": "Apache License 2.0",
    "lpi_default": "basic",
    "mod": "vrtrelay",
    "mods_required": [],
    "oid": "phi:uc/mws1-v1/test2",
    "required": [
        "port_get",
        "port_set"
    ],
    "version": "1.0.1"
}

Parameters:

  • API Key API key with master permissions
  • m PHI module

Optionally:

  • c PHI configuration
  • save save driver configuration after successful call

set PHI configuration property

appends property to PHI configuration and reloads module

http

PATCH /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "default_status": 1 }

curl

curl -i -X PATCH http://localhost:8812/r/phi/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"default_status": 1, "save": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/phi/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"default_status": 1, "save": true}'

httpie

echo '{
  "default_status": 1,
  "save": true
}' | http PATCH http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/phi/test1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'default_status': 1,
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

test PHI

Get PHI test result (as-is). All PHIs respond to self command, help command returns all available test commands.

http

POST /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "c": "self", "method": "test" }

curl

curl -i -X POST http://localhost:8812/r/phi/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "self", "method": "test"}'

wget

wget -S -O- http://localhost:8812/r/phi/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "self", "method": "test"}'

httpie

echo '{
  "c": "self",
  "method": "test"
}' | http POST http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/phi/test1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': 'self',
    'method': 'test',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "output": "OK"
}

Parameters:

  • API Key API key with master permissions

unload PHI

Unloads PHI. PHI should not be used by any driver (except default, but the driver should not be in use by any item).

If driver <phi_id.default> (which’s loaded automatically with PHI) is present, it will be unloaded as well.

http

DELETE /r/phi/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/phi/test2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/phi/test2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/phi/test2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/phi/test2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

upload PHI module

Allows to upload new PHI module to xc/drivers/phi folder.

http

PUT /r/phi-module/gpio_button HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "c": "<MODULE_CONTENT>" }

curl

curl -i -X PUT http://localhost:8812/r/phi-module/gpio_button -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "<MODULE_CONTENT>"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/phi-module/gpio_button --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"c": "<MODULE_CONTENT>"}'

httpie

echo '{
  "c": "<MODULE_CONTENT>"
}' | http PUT http://localhost:8812/r/phi-module/gpio_button Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/phi-module/gpio_button', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': '<MODULE_CONTENT>',
})

response

HTTP/1.1 201 Created
Content-Type: application/json
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0

{
    "api": 1,
    "author": "Altertech Group, https://www.altertech.com/",
    "description": "GPIO buttons",
    "equipment": [
        "GPIO buttons"
    ],
    "features": [
        "events"
    ],
    "help": " Handling pressed events from GPIO buttons.\n\nPHI doesn't provide any control/monitoring functions, each button can be\nconfigured as unit (via basic LPI) or sensor (via sensor) and contain its port\nin update_driver_config, update_interval should be set to 0.\n",
    "license": "Apache License 2.0",
    "lpi_default": "sensor",
    "mod": "gpio_button",
    "mods_required": [
        "gpiozero"
    ],
    "oid": null,
    "required": [],
    "version": "1.0.0"
}

Parameters:

  • API Key API key with master permissions
  • c module content

Optionally:

  • force overwrite PHI module file if exists

LPI and drivers

assign driver to item

Sets the specified driver to item, automatically updating item props:

  • action_driver_config,**update_driver_config** to the specified configuration * action_exec, update_exec to do all operations via driver function calls (sets both to |<driver_id>)

To unassign driver, set driver ID to empty/null.

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "c": "port=5", "method": "assign_driver", "d": "test2.my" }

curl

curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "port=5", "d": "test2.my", "method": "assign_driver"}'

wget

wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "port=5", "d": "test2.my", "method": "assign_driver"}'

httpie

echo '{
  "c": "port=5",
  "d": "test2.my",
  "method": "assign_driver"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': 'port=5',
    'd': 'test2.my',
    'method': 'assign_driver',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key masterkey
  • d driver ID (if none - all above item props are set to null)
  • c configuration (e.g. port number)

Optionally:

  • save save item configuration after successful call

get LPI module info

http

GET /r/lpi-module/multistep HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/lpi-module/multistep -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/lpi-module/multistep --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/lpi-module/multistep X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/lpi-module/multistep', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "api": 1,
    "author": "Altertech Group, https://www.altertech.com/",
    "connections": {
        "dport": "destination",
        "port": "power"
    },
    "description": "Multistep LPI (opener)",
    "features": [
        "action",
        "action_mp",
        "port_set",
        "aao_set"
    ],
    "help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration.  Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
    "license": "Apache License 2.0",
    "logic": "multistep with delays",
    "mod": "multistep",
    "oid": null,
    "version": "1.0.0"
}

Parameters:

  • API Key API key with master permissions

get LPI usage help

http

GET /r/lpi-module/multistep?help=cfg HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i 'http://localhost:8812/r/lpi-module/multistep?help=cfg' -H 'X-Auth-Key: mykey'

wget

wget -S -O- 'http://localhost:8812/r/lpi-module/multistep?help=cfg' --header='X-Auth-Key: mykey'

httpie

http 'http://localhost:8812/r/lpi-module/multistep?help=cfg' X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/lpi-module/multistep?help=cfg', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "help": "allow action even if current status is error",
        "name": "bose",
        "required": false,
        "type": "bool"
    }
]

Parameters:

  • API Key API key with master permissions

get list of available LPI modules

http

GET /r/lpi-module HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/lpi-module -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/lpi-module --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/lpi-module X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/lpi-module', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "api": 1,
        "author": "Altertech Group, https://www.altertech.com/",
        "connections": {
            "port": "primary"
        },
        "description": "Basic LPI for simple devices",
        "features": [
            "status",
            "status_mp",
            "mu_status",
            "mu_status_mp",
            "port_get",
            "aao_get",
            "action",
            "action_mp",
            "port_set",
            "aao_set",
            "events"
        ],
        "help": "\nBasic LPI for simple unit status control (on/off) and monitoring. Support\nstatus 0 and 1. Unit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port' i.e. to\n'socket' for a more fancy unit configuration. Each port may be specified as a\nsingle value or contain an array of values, in this case multiple ports are\nused simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state.\n",
        "id": null,
        "license": "Apache License 2.0",
        "logic": "basic status on/off",
        "lpi_id": null,
        "mod": "basic",
        "oid": null,
        "phi_id": null,
        "version": "1.0.0"
    }
]

Parameters:

  • API Key API key with master permissions

get loaded driver information

http

GET /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/driver/test2.my -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/driver/test2.my --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/driver/test2.my X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/driver/test2.my', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "api": 1,
    "author": "Altertech Group, https://www.altertech.com/",
    "cfg": {},
    "connections": {
        "dport": "destination",
        "port": "power"
    },
    "description": "Multistep LPI (opener)",
    "features": [
        "action",
        "action_mp",
        "port_set",
        "aao_set"
    ],
    "help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration.  Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
    "id": "test2.my",
    "license": "Apache License 2.0",
    "logic": "multistep with delays",
    "lpi_id": "my",
    "mod": "multistep",
    "oid": "driver:uc/mws1-v1/test2.my",
    "phi": {
        "api": 1,
        "author": "Altertech Group, https://www.altertech.com/",
        "cfg": {
            "default_status": 0
        },
        "description": "Emulates 16-port relay",
        "equipment": [
            "virtual"
        ],
        "features": [
            "port_get",
            "port_set",
            "aao_set",
            "aao_get"
        ],
        "help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
        "id": "test2",
        "license": "Apache License 2.0",
        "lpi_default": "basic",
        "mod": "vrtrelay",
        "mods_required": [],
        "oid": "phi:uc/mws1-v1/test2",
        "required": [
            "port_get",
            "port_set"
        ],
        "version": "1.0.1"
    },
    "phi_id": "test2",
    "version": "1.0.0"
}

Parameters:

  • API Key API key with master permissions

list loaded drivers

http

GET /r/driver HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/driver -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/driver --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/driver X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/driver', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "features": [
            "action",
            "action_mp",
            "port_set",
            "aao_set"
        ],
        "id": "test.bose",
        "lpi_id": "bose",
        "mod": "multistep",
        "phi_id": "test"
    },
    {
        "features": [
            "status",
            "status_mp",
            "mu_status",
            "mu_status_mp",
            "port_get",
            "aao_get",
            "action",
            "action_mp",
            "port_set",
            "aao_set",
            "events"
        ],
        "id": "test.default",
        "lpi_id": "default",
        "mod": "basic",
        "phi_id": "test"
    }
]

Parameters:

  • API Key API key with master permissions
  • full get exntended information

load a driver

Loads a driver, combining previously loaded PHI and chosen LPI module.

http

PUT /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "m": "multistep" }

curl

curl -i -X PUT http://localhost:8812/r/driver/test2.my -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "multistep"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/driver/test2.my --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"m": "multistep"}'

httpie

echo '{
  "m": "multistep"
}' | http PUT http://localhost:8812/r/driver/test2.my Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/driver/test2.my', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'm': 'multistep',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "api": 1,
    "author": "Altertech Group, https://www.altertech.com/",
    "cfg": {},
    "connections": {
        "dport": "destination",
        "port": "power"
    },
    "description": "Multistep LPI (opener)",
    "features": [
        "action",
        "action_mp",
        "port_set",
        "aao_set"
    ],
    "help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration.  Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
    "id": "test2.my",
    "license": "Apache License 2.0",
    "logic": "multistep with delays",
    "lpi_id": "my",
    "mod": "multistep",
    "oid": "driver:uc/mws1-v1/test2.my",
    "phi": {
        "api": 1,
        "author": "Altertech Group, https://www.altertech.com/",
        "cfg": {
            "default_status": 0
        },
        "description": "Emulates 16-port relay",
        "equipment": [
            "virtual"
        ],
        "features": [
            "port_get",
            "port_set",
            "aao_set",
            "aao_get"
        ],
        "help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
        "id": "test2",
        "license": "Apache License 2.0",
        "lpi_default": "basic",
        "mod": "vrtrelay",
        "mods_required": [],
        "oid": "phi:uc/mws1-v1/test2",
        "required": [
            "port_get",
            "port_set"
        ],
        "version": "1.0.1"
    },
    "phi_id": "test2",
    "version": "1.0.0"
}

Parameters:

  • API Key API key with master permissions
  • m LPI module

Optionally:

  • c Driver (LPI) configuration, optional
  • save save configuration after successful call

set driver (LPI) configuration property

appends property to LPI configuration and reloads module

http

PATCH /r/driver/test1.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "bose": 1 }

curl

curl -i -X PATCH http://localhost:8812/r/driver/test1.my -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"bose": 1, "save": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/driver/test1.my --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"bose": 1, "save": true}'

httpie

echo '{
  "bose": 1,
  "save": true
}' | http PATCH http://localhost:8812/r/driver/test1.my Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/driver/test1.my', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'bose': 1,
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save driver configuration after successful call

unload driver

Unloads driver. Driver should not be used by any item.

http

DELETE /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/driver/test2.my -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/driver/test2.my --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/driver/test2.my X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/driver/test2.my', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Devices

delete device items

Works in an opposite way to deploy_device - deploy device items from template function, destroying all items specified in the template.

http

POST /r/device-tpl/device1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "c": "PORT=2,ID=5", "method": "undeploy", "c": "PORT=3,ID=7" }

curl

curl -i -X POST http://localhost:8812/r/device-tpl/device1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "PORT=3,ID=7", "method": "undeploy"}'

wget

wget -S -O- http://localhost:8812/r/device-tpl/device1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "PORT=3,ID=7", "method": "undeploy"}'

httpie

echo '{
  "c": "PORT=3,ID=7",
  "method": "undeploy"
}' | http POST http://localhost:8812/r/device-tpl/device1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/device-tpl/device1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': 'PORT=3,ID=7',
    'method': 'undeploy',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with allow=device permissions
  • t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)

Optionally:

  • c device config (var=value, comma separated or dict)

Returns:

The function ignores missing items, so no errors are returned unless device configuration file is invalid.

deploy device items from template

Deploys the device from the specified template.

http

POST /r/device-tpl/device1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "deploy", "c": "PORT=3,ID=7", "save": true }

curl

curl -i -X POST http://localhost:8812/r/device-tpl/device1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "PORT=3,ID=7", "method": "deploy", "save": true}'

wget

wget -S -O- http://localhost:8812/r/device-tpl/device1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "PORT=3,ID=7", "method": "deploy", "save": true}'

httpie

echo '{
  "c": "PORT=3,ID=7",
  "method": "deploy",
  "save": true
}' | http POST http://localhost:8812/r/device-tpl/device1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/device-tpl/device1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': 'PORT=3,ID=7',
    'method': 'deploy',
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with allow=device permissions
  • t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)

Optionally:

  • c device config (var=value, comma separated or dict)
  • save save items configuration on disk immediately after operation

list device templates

List available device templates from runtime/tpl

http

GET /r/device-tpl HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/device-tpl -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/device-tpl --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/device-tpl X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/device-tpl', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "name": "asic",
        "type": "JSON"
    },
    {
        "name": "device1",
        "type": "YAML"
    },
    {
        "name": "weatherapp",
        "type": "JSON"
    }
]

Parameters:

  • API Key API key with masterkey permissions

update device items

Works similarly to deploy_device - deploy device items from template function but doesn’t create new items, updating the item configuration of the existing ones.

http

POST /r/device-tpl/device1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "update", "c": "PORT=3,ID=7", "save": true }

curl

curl -i -X POST http://localhost:8812/r/device-tpl/device1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "PORT=3,ID=7", "method": "update", "save": true}'

wget

wget -S -O- http://localhost:8812/r/device-tpl/device1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "PORT=3,ID=7", "method": "update", "save": true}'

httpie

echo '{
  "c": "PORT=3,ID=7",
  "method": "update",
  "save": true
}' | http POST http://localhost:8812/r/device-tpl/device1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/device-tpl/device1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'c': 'PORT=3,ID=7',
    'method': 'update',
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with allow=device permissions
  • t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)

Optionally:

  • c device config (var=value, comma separated or dict)
  • save save items configuration on disk immediately after operation

CVARs

get the value of user-defined variable

Note

Even if different EVA controllers are working on the same server, they have different sets of variables To set the variables for each subsystem, use SYS API on the respective address/port.

http

GET /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/cvar/test -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/cvar/test --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/cvar/test X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/cvar/test', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "test": "some_value"
}

Parameters:

  • API Key API key with master permissions

Optionally:

Returns:

Dict containing variable and its value. If no varible name was specified, all cvars are returned.

set the value of user-defined variable

http

PUT /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "v": "some_value" }

curl

curl -i -X PUT http://localhost:8812/r/cvar/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "some_value"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/cvar/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": "some_value"}'

httpie

echo '{
  "v": "some_value"
}' | http PUT http://localhost:8812/r/cvar/test Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/cvar/test', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'v': 'some_value',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "test": "some_value"
}

Parameters:

  • API Key API key with master permissions

Optionally:

  • v variable value (if not specified, variable is deleted)

Locking functions

acquire lock

Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:

  • centralized for several systems (any EVA server can act as lock server)
  • removed from outside
  • automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock

used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.

Note

Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.

http

PUT /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "e": 1, "t": 15 }

curl

curl -i -X PUT http://localhost:8812/r/lock/mylock1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": 1, "t": 15}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/lock/mylock1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": 1, "t": 15}'

httpie

echo '{
  "e": 1,
  "t": 15
}' | http PUT http://localhost:8812/r/lock/mylock1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/lock/mylock1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'e': 1,
    't': 15,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": "mylock1",
    "type": "lock"
}

Parameters:

  • API Key API key with allow=lock permissions

Optionally:

  • t maximum time (seconds) to acquire lock
  • e time after which lock is automatically released (if absent, lock may be released only via unlock function)

get lock status

http

GET /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/lock/mylock1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": "mylock1",
    "locked": true,
    "type": "lock"
}

Parameters:

  • API Key API key with allow=lock permissions

release lock

Releases the previously acquired lock.

http

DELETE /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/lock/mylock1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with allow=lock permissions

Logging

put message to log file

An external application can put a message in the logs on behalf of the controller.

http

POST /r/log/warning HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "m": "local file system is full" }

curl

curl -i -X POST http://localhost:8812/r/log/warning -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "local file system is full"}'

wget

wget -S -O- http://localhost:8812/r/log/warning --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"m": "local file system is full"}'

httpie

echo '{
  "m": "local file system is full"
}' | http POST http://localhost:8812/r/log/warning Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/log/warning', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'm': 'local file system is full',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with sysfunc=yes permissions
  • l log level
  • m message text

put debug message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put info message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put warning message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put error message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put critical message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

get records from the controller log

Log records are stored in the controllers’ memory until restart or the time (keep_logmem) specified in controller configuration passes.

http

GET /r/log/warning?t=3600&n=3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i 'http://localhost:8812/r/log/warning?t=3600&n=3' -H 'X-Auth-Key: mykey'

wget

wget -S -O- 'http://localhost:8812/r/log/warning?t=3600&n=3' --header='X-Auth-Key: mykey'

httpie

http 'http://localhost:8812/r/log/warning?t=3600&n=3' X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/log/warning?t=3600&n=3', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "h": "mws1-v1",
        "l": 30,
        "mod": "sysapi",
        "msg": "test warning message",
        "p": "uc",
        "t": 1552863481.1394246,
        "th": "CP Server Thread-15"
    },
    {
        "h": "mws1-v1",
        "l": 40,
        "mod": "sysapi",
        "msg": "test error message",
        "p": "uc",
        "t": 1552863481.1516943,
        "th": "CP Server Thread-16"
    },
    {
        "h": "mws1-v1",
        "l": 50,
        "mod": "sysapi",
        "msg": "test critical message",
        "p": "uc",
        "t": 1552863481.1631815,
        "th": "CP Server Thread-17"
    }
]

Parameters:

  • API Key API key with sysfunc=yes permissions

Optionally:

  • t get log records not older than t seconds
  • n the maximum number of log records you want to obtain

rotate log file

Equal to kill -HUP <controller_process_pid>.

http

POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "log_rotate" }

curl

curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "log_rotate"}'

wget

wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "log_rotate"}'

httpie

echo '{
  "method": "log_rotate"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'log_rotate',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with sysfunc=yes permissions

API keys

create API key

API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.

Keys with master permission can not be created.

http

PUT /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "sysfunc": true, "allow": "cmd" }

curl

curl -i -X PUT http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"allow": "cmd", "save": true, "sysfunc": true}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"allow": "cmd", "save": true, "sysfunc": true}'

httpie

echo '{
  "allow": "cmd",
  "save": true,
  "sysfunc": true
}' | http PUT http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/key/testkey2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'allow': 'cmd',
    'save': True,
    'sysfunc': True,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "allow": [
        "cmd"
    ],
    "dynamic": true,
    "groups": [],
    "hosts_allow": [
        "0.0.0.0/0"
    ],
    "hosts_assign": [],
    "id": "testkey2",
    "items": [],
    "key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
    "master": false,
    "pvt": [],
    "rpvt": [],
    "sysfunc": true
}

Parameters:

  • API Key API key with master permissions
  • save save configuration immediately

Returns:

JSON with serialized key object

delete API key

http

DELETE /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/key/testkey2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

list API key permissions

Lists API key permissons (including a key itself)

Note

API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.

http

GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/key/testkey2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "allow": [
        "cmd"
    ],
    "dynamic": true,
    "groups": [],
    "hosts_allow": [
        "0.0.0.0/0"
    ],
    "hosts_assign": [],
    "id": "testkey2",
    "items": [],
    "key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
    "master": false,
    "pvt": [],
    "rpvt": [],
    "sysfunc": true
}

Parameters:

  • API Key API key with master permissions
  • save save configuration immediately

list API keys

http

GET /r/key HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/key -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/key --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/key X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/key', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "dynamic": false,
        "key_id": "masterkey",
        "master": true
    },
    {
        "allow": {
            "cmd": true,
            "device": true,
            "lock": false
        },
        "dynamic": true,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "default",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": true,
            "device": true,
            "lock": false
        },
        "dynamic": false,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "lm",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": false,
            "device": true,
            "lock": true
        },
        "dynamic": false,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "operator",
        "master": false,
        "sysfunc": true
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": false,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "sfa",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": true,
        "groups": [],
        "items": [
            "item1"
        ],
        "key_id": "t4",
        "master": false,
        "sysfunc": true
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": false,
        "groups": [],
        "items": [
            "sensor:sensors/sensor1"
        ],
        "key_id": "test",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": true,
        "groups": [],
        "items": [],
        "key_id": "testkey",
        "master": false,
        "sysfunc": true
    },
    {
        "allow": {
            "cmd": true,
            "device": false,
            "lock": false
        },
        "dynamic": true,
        "groups": [],
        "items": [],
        "key_id": "testkey2",
        "master": false,
        "sysfunc": true
    }
]

Parameters:

  • API Key API key with master permissions

regenerate API key

http

POST /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "regenerate" }

curl

curl -i -X POST http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "regenerate"}'

wget

wget -S -O- http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "regenerate"}'

httpie

echo '{
  "method": "regenerate"
}' | http POST http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/key/testkey2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'regenerate',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "3dbcd3d24c6dc878cebe369eb9fdb95ae99fee14e99cdfd911b83629688d2854"
}

Parameters:

  • API Key API key with master permissions

Returns:

JSON dict with new key value in “key” field

set API key permissions

http

PATCH /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "sysfunc": true }

curl

curl -i -X PATCH http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "sysfunc": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "sysfunc": true}'

httpie

echo '{
  "save": true,
  "sysfunc": true
}' | http PATCH http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/key/testkey2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'save': True,
    'sysfunc': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • p property
  • v value (if none, permission will be revoked)
  • save save configuration immediately

User accounts

assign API key to user

http

PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "a": "masterkey" }

curl

curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "masterkey"}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "masterkey"}'

httpie

echo '{
  "a": "masterkey"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/user/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': 'masterkey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • a API key to assign (key id, not a key itself)

create user account

Note

All changes to user accounts are instant, if the system works in read/only mode, set it to read/write before performing user management.

http

PUT /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "p": "verysecretpassword", "a": "testkey" }

curl

curl -i -X PUT http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "testkey", "p": "verysecretpassword"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "testkey", "p": "verysecretpassword"}'

httpie

echo '{
  "a": "testkey",
  "p": "verysecretpassword"
}' | http PUT http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/user/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': 'testkey',
    'p': 'verysecretpassword',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "testkey",
    "user": "test2"
}

Parameters:

  • API Key API key with master permissions
  • p user password
  • a API key to assign (key id, not a key itself)

delete user account

http

DELETE /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/user/test2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/user/test2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get user account info

http

GET /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/user/test2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/user/test2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "testkey",
    "user": "test2"
}

Parameters:

  • API Key API key with master permissions

list user accounts

http

GET /r/user HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/user -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/user --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/user X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/user', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "key_id": "test",
        "user": "divisor"
    },
    {
        "key_id": "testkey",
        "user": "test"
    },
    {
        "key_id": "testkey",
        "user": "test2"
    }
]

Parameters:

  • API Key API key with master permissions

set user password

http

PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "p": "qwerty" }

curl

curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"p": "qwerty"}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"p": "qwerty"}'

httpie

echo '{
  "p": "qwerty"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/user/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'p': 'qwerty',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • p new password

Notifier management

disable notifier

Note

The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.

http

PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "enabled": false }

curl

curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false}'

httpie

echo '{
  "enabled": false
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'enabled': False,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

enable notifier

Note

The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.

http

PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "enabled": true }

curl

curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true}'

httpie

echo '{
  "enabled": true
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'enabled': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get notifier configuration

http

GET /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/notifier/eva_1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/notifier/eva_1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/notifier/eva_1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/notifier/eva_1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "announce_interval": 5.0,
    "api_enabled": true,
    "enabled": false,
    "events": [
        {
            "groups": [
                "#"
            ],
            "subject": "state",
            "types": [
                "#"
            ]
        },
        {
            "level": 30,
            "subject": "log"
        }
    ],
    "host": "mws1-v1",
    "id": "eva_1",
    "password": "test",
    "qos": {
        "action": 2,
        "log": 2,
        "state": 2,
        "system": 2
    },
    "type": "mqtt",
    "username": "eva"
}

Parameters:

  • API Key API key with master permissions

list notifiers

http

GET /r/notifier HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/notifier -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/notifier --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/notifier X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/notifier', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "db": "db1.db",
        "enabled": true,
        "events": [
            {
                "groups": [
                    "#"
                ],
                "subject": "state",
                "types": [
                    "#"
                ]
            }
        ],
        "id": "db_1",
        "keep": 86400,
        "type": "db"
    },
    {
        "announce_interval": 5.0,
        "api_enabled": true,
        "enabled": false,
        "events": [
            {
                "groups": [
                    "#"
                ],
                "subject": "state",
                "types": [
                    "#"
                ]
            },
            {
                "level": 30,
                "subject": "log"
            }
        ],
        "host": "mws1-v1",
        "id": "eva_1",
        "password": "test",
        "qos": {
            "action": 2,
            "log": 2,
            "state": 2,
            "system": 2
        },
        "type": "mqtt",
        "username": "eva"
    }
]

Parameters:

  • API Key API key with master permissions

File management

put file to runtime folder

Puts a new file into runtime folder. If the file with such name exists, it will be overwritten. As all files in runtime are text, binary data can not be put.

http

PUT /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "m": "/bin/sh\n\nexit 0", "e": true }

curl

curl -i -X PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true, "m": "/bin/sh\n\nexit 0"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true, "m": "/bin/sh\n\nexit 0"}'

httpie

echo '{
  "e": true,
  "m": "/bin/sh\n\nexit 0"
}' | http PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'e': True,
    'm': '/bin/sh\n\nexit 0',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": "xc/uc/test_action_script2",
    "type": "runtime"
}

Parameters:

  • API Key API key with master permissions
  • m file content

set file exec permission

http

PATCH /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "e": true, "e": true }

curl

curl -i -X PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true}'

httpie

echo '{
  "e": true
}' | http PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'e': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • e false for 0x644, true for 0x755 (executable)

delete file from runtime folder

http

DELETE /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get file contents from runtime folder

http

GET /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "data": "/bin/sh\n\nexit 0",
    "e": true,
    "file": "xc/uc/test_action_script2"
}

Parameters:

  • API Key API key with master permissions