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 see UC API.
RESTful API basics
Warning
RESTful API is deprecated and scheduled to be removed (not implemented) in EVA ICS v4. Use JSON RPC API, whenever it is possible.
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.
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.
Long API calls
Long API calls should be avoided at any cost.
All critical action and command methods have an option to obtain action ID and check for the result later.
If long API calls are performed between controllers (e.g. action methods with wait param), remote controller timeout should be always greater than max. expected “wait” timeout in API call, otherwise client controller will repeat API calls continuously, up to max retries for the target controller.
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.
For SFA, the result section “connected” contains connection status of remote controllers. The API key must have an access either to “uc” and “lm” groups (“remote_uc:uc” and “remote_lm:lm”) or to particular controller oids.
GET /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/core -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/core --header="X-Auth-Key: mykey"
http http://localhost:8812/r/core X-Auth-Key:mykey
requests.get('http://localhost:8812/r/core', headers={'X-Auth-Key': 'mykey'})
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).
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
curl -i -X POST http://localhost:8812/r/core -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "save"}'
wget -S -O- http://localhost:8812/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "save"}'
echo '{
"method": "save"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/core', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'save'})
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
Clear language cache
check access to the particular item
Does not check is supervisor lock set, also does not check the item really exist
Parameters:
API Key valid API key
i item id or list of ids
Returns:
oid list with subobjects “r”, “w” (true/false)
execute a remote system command
Executes a command script on the server where the controller is installed.
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 -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 -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}'
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
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})
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) or array (list)
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
s STDIN data
get list of loaded core plugins
GET /r/plugin HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/plugin -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/plugin --header="X-Auth-Key: mykey"
http http://localhost:8812/r/plugin X-Auth-Key:mykey
requests.get('http://localhost:8812/r/plugin', headers={'X-Auth-Key': 'mykey'})
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
[
{
"author": "Altertech, https://www.altertech.com/",
"license": "Apache License 2.0",
"name": "test",
"version": "0.0.1"
}
]
Parameters:
API Key API key with master permissions
Returns:
list with plugin module information
install a package
Parameters:
API Key API key with master permissions
m package content (base64-encoded tar/tgz)
o package setup options
w wait (in seconds) before API call sends a response. This allows to try waiting until the package is installed
shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
For MQTT API calls a small shutdown delay usually should be specified to let the core send the correct API response.
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "shutdown" }
curl -i -X POST http://localhost:8812/r/core -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "shutdown"}'
wget -S -O- http://localhost:8812/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "shutdown"}'
echo '{
"method": "shutdown"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/core', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'shutdown'})
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
Returns:
current boot id. This allows client to check is the controller restarted later, by comparing returned boot id and new boot id (obtained with “test” command)
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.
PATCH /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "debug": true }
curl -i -X PATCH http://localhost:8812/r/core -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"debug": true}'
wget -S -O- --method=PATCH http://localhost:8812/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --body-data='{"debug": true}'
echo '{
"debug": true
}' | http PATCH http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/core', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'debug': True})
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 an 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.
If both token and credentials (user or API key) are specified, the function will return the token to normal mode.
POST /r/token HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl -i -X POST http://localhost:8812/r/token -H "Content-Type: application/json" --data-raw '{"p": "123", "u": "admin"}'
wget -S -O- http://localhost:8812/r/token --header="Content-Type: application/json" --post-data='{"p": "123", "u": "admin"}'
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8812/r/token Content-Type:application/json
requests.post('http://localhost:8812/r/token', headers={'Content-Type': 'application/json'}, json={'p': '123', 'u': 'admin'})
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 the authentication token
DELETE /r/token HTTP/1.1
Host: localhost:8812
X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
curl -i -X DELETE http://localhost:8812/r/token -H "X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
wget -S -O- --method=DELETE http://localhost:8812/r/token --header="X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
http DELETE http://localhost:8812/r/token X-Auth-Key:token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
requests.delete('http://localhost:8812/r/token', headers={'X-Auth-Key': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'})
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
Set token read-only
Applies read-only mode for token. In read-only mode, only read-only functions work, others return result_token_restricted(15).
The method works for token-authenticated API calls only.
To exit read-only mode, user must either re-login or, to keep the current token, call “login” API method with both token and user credentials.
Get neighbor clients
Parameters:
API Key valid API key
i neightbor client id
Item functions
clean action queue of unit
Cancels all queued actions, keeps the current action running.
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "q_clean" }
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 -S -O- http://localhost:8812/r/unit/tests/unit3 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "q_clean"}'
echo '{
"method": "q_clean"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'q_clean'})
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.
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "action_enabled": false }
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 -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}'
echo '{
"action_enabled": false
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'action_enabled': False})
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.
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "action_enabled": true }
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 -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}'
echo '{
"action_enabled": true
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'action_enabled': True})
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.
GET /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/action -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/action --header="X-Auth-Key: mykey"
http http://localhost:8812/r/action X-Auth-Key:mykey
requests.get('http://localhost:8812/r/action', headers={'X-Auth-Key': 'mykey'})
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.
GET /r/unit/@groups HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/unit/@groups -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/unit/@groups --header="X-Auth-Key: mykey"
http http://localhost:8812/r/unit/@groups X-Auth-Key:mykey
requests.get('http://localhost:8812/r/unit/@groups', headers={'X-Auth-Key': 'mykey'})
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.
GET /r/sensor HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/sensor -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/sensor --header="X-Auth-Key: mykey"
http http://localhost:8812/r/sensor X-Auth-Key:mykey
requests.get('http://localhost:8812/r/sensor', headers={'X-Auth-Key': 'mykey'})
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, the method attempts to get stored state for an item even if it doesn’t present currently in system.
The method can return state log for disconnected items as well.
GET /r/sensor/tests/sensor2@history HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/sensor/tests/sensor2@history -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/sensor/tests/sensor2@history --header="X-Auth-Key: mykey"
http http://localhost:8812/r/sensor/tests/sensor2@history X-Auth-Key:mykey
requests.get('http://localhost:8812/r/sensor/tests/sensor2@history', headers={'X-Auth-Key': 'mykey'})
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”)
z Time zone (pytz, e.g. UTC or Europe/Prague)
w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
g output format (“list”, “dict” or “chart”, default is “list”)
c options for chart (dict or comma separated)
o extra options for notifier data request
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
type: chart type (line or bar, default is line)
tf: chart time format
out: output format (svg, png, default is svg),
style: chart style (without “Style” suffix, e.g. Dark)
other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
get item state log
State log of a single item or group of the specified type can be obtained using state_log command.
note: only SQL notifiers are supported
Difference from state_history method:
state_log doesn’t optimize data to be displayed on charts * the data is returned from a database as-is * a single item OID or OID mask (e.g. sensor:env/#) can be specified
note: the method supports MQTT-style masks but only masks with wildcard-ending, like “type:group/subgroup/#” are supported.
The method can return state log for disconnected items as well.
For wildcard fetching, API key should have an access to the whole chosen group.
note: record limit means the limit for records, fetched from the database, but repeating state records are automatically grouped and the actual number of returned records can be lower than requested.
GET /r/sensor/tests/test1@log HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/sensor/tests/test1@log -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/sensor/tests/test1@log --header="X-Auth-Key: mykey"
http http://localhost:8812/r/sensor/tests/test1@log X-Auth-Key:mykey
requests.get('http://localhost:8812/r/sensor/tests/test1@log', headers={'X-Auth-Key': 'mykey'})
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
[
{
"oid": "sensor:tests/test1",
"status": 1,
"t": 1607295099.9760036,
"value": null
},
{
"oid": "sensor:tests/test1",
"status": 1,
"t": 1607295103.9991317,
"value": 25.0
},
{
"oid": "sensor:tests/test1",
"status": 1,
"t": 1607295107.0097003,
"value": 258.0
},
{
"oid": "sensor:tests/test1",
"status": 1,
"t": 1607295110.0616019,
"value": 359.0
}
]
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”)
t time format (“iso” or “raw” for unix timestamp, default is “raw”)
z Time zone (pytz, e.g. UTC or Europe/Prague)
o extra options for notifier data request
Returns:
state log records (list)
kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "kill" }
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 -S -O- http://localhost:8812/r/unit/tests/unit3 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "kill"}'
echo '{
"method": "kill"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'kill'})
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
PATCH /r/sensor/tests/sensor1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "maintenance": true }
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 -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}'
echo '{
"maintenance": true
}' | http PATCH http://localhost:8812/r/sensor/tests/sensor1 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/sensor/tests/sensor1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'maintenance': True})
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
PATCH /r/sensor/tests/sensor1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "maintenance": false }
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 -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}'
echo '{
"maintenance": false
}' | http PATCH http://localhost:8812/r/sensor/tests/sensor1 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/sensor/tests/sensor1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'maintenance': False})
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
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "terminate" }
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 -S -O- http://localhost:8812/r/unit/tests/unit3 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "terminate"}'
echo '{
"method": "terminate"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'terminate'})
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)
POST /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "i": "unit:tests/unit3", "s": "toggle" }
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 -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"}'
echo '{
"i": "unit:tests/unit3",
"s": "toggle"
}' | http POST http://localhost:8812/r/action Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/action', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'i': 'unit:tests/unit3', 's': 'toggle'})
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.
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 -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 -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}'
echo '{
"i": "unit:tests/unit3",
"s": 1
}' | http POST http://localhost:8812/r/action Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/action', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'i': 'unit:tests/unit3', 's': 1})
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.
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 -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 -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}'
echo '{
"s": 1,
"v": 29.445
}' | http POST http://localhost:8812/r/sensor/tests/sensor2 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/sensor/tests/sensor2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'s': 1, 'v': 29.445})
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.
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 -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 -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}'
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
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})
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 sensor
Creates new sensor.
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 -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 -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}'
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
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})
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.
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 -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 -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}'
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
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})
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
get item configuration
GET /r/unit/tests/unit3@config HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/unit/tests/unit3@config -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/unit/tests/unit3@config --header="X-Auth-Key: mykey"
http http://localhost:8812/r/unit/tests/unit3@config X-Auth-Key:mykey
requests.get('http://localhost:8812/r/unit/tests/unit3@config', headers={'X-Auth-Key': 'mykey'})
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.
GET /r/unit/tests/unit1@props HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/unit/tests/unit1@props -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/unit/tests/unit1@props --header="X-Auth-Key: mykey"
http http://localhost:8812/r/unit/tests/unit1@props X-Auth-Key:mykey
requests.get('http://localhost:8812/r/unit/tests/unit1@props', headers={'X-Auth-Key': 'mykey'})
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_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)
POST /r/unit/tests/unit1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
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 -S -O- http://localhost:8812/r/unit/tests/unit1 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "save"}'
echo '{
"method": "save"
}' | http POST http://localhost:8812/r/unit/tests/unit1 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/unit/tests/unit1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'save'})
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.
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 -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 -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}'
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
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})
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.
POST /r/unit/tests/ HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "clone", "n": "clone_tests" }
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 -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"}'
echo '{
"method": "clone",
"n": "clone_tests"
}' | http POST http://localhost:8812/r/unit/tests/ Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/unit/tests/', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'clone', 'n': 'clone_tests'})
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.
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 -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 -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"}'
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
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'})
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.
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 -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 -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}'
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
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})
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.
DELETE /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/owfs/bus1 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/owfs/bus1 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/owfs/bus1 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/owfs/bus1', headers={'X-Auth-Key': 'mykey'})
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
GET /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/owfs/bus1 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/owfs/bus1 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/owfs/bus1 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/owfs/bus1', headers={'X-Auth-Key': 'mykey'})
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
GET /r/owfs HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/owfs -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/owfs --header="X-Auth-Key: mykey"
http http://localhost:8812/r/owfs X-Auth-Key:mykey
requests.get('http://localhost:8812/r/owfs', headers={'X-Auth-Key': 'mykey'})
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.
POST /r/owfs/bus_local HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "scan" }
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 -S -O- http://localhost:8812/r/owfs/bus_local --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "scan"}'
echo '{
"method": "scan"
}' | http POST http://localhost:8812/r/owfs/bus_local Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/owfs/bus_local', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'scan'})
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.
POST /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "test" }
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 -S -O- http://localhost:8812/r/owfs/bus1 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "test"}'
echo '{
"method": "test"
}' | http POST http://localhost:8812/r/owfs/bus1 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/owfs/bus1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'test'})
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
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 -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 -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}'
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
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})
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.
DELETE /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/modbus/mbp2 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/modbus/mbp2 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/modbus/mbp2 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/modbus/mbp2', headers={'X-Auth-Key': 'mykey'})
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
GET /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/modbus/mbp2 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/modbus/mbp2 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/modbus/mbp2 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/modbus/mbp2', headers={'X-Auth-Key': 'mykey'})
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
GET /r/modbus HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/modbus -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/modbus --header="X-Auth-Key: mykey"
http http://localhost:8812/r/modbus X-Auth-Key:mykey
requests.get('http://localhost:8812/r/modbus', headers={'X-Auth-Key': 'mykey'})
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
Float32 numbers are returned as Python-converted floats and may have broken precision. Consider converting back to f32 on the client side.
GET /r/modbus/local/1/h10-12,c5-6 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/modbus/local/1/h10-12,c5-6 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/modbus/local/1/h10-12,c5-6 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/modbus/local/1/h10-12,c5-6 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/modbus/local/1/h10-12,c5-6', headers={'X-Auth-Key': 'mykey'})
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
f data type (u16, i16, u32, i32, u64, i64, f32 or bit)
c count, if register range not specified
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.
POST /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "test" }
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 -S -O- http://localhost:8812/r/modbus/mbp2 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "test"}'
echo '{
"method": "test"
}' | http POST http://localhost:8812/r/modbus/mbp2 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/modbus/mbp2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'test'})
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).
To set bit, specify register as hX/Y where X = register number, Y = bit number (supports u16, u32, u64 data types)
PUT /r/modbus/local/1/h10 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "v": 2522 }
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 -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}'
echo '{
"v": 2522
}' | http PUT http://localhost:8812/r/modbus/local/1/h10 Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/modbus/local/1/h10', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'v': 2522})
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)
f data type (u16, i16, u32, i32, u64, i64, f32), ignored if z=True
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
GET /r/modbus-slave/h1000-1005,c10-15 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/modbus-slave/h1000-1005,c10-15', headers={'X-Auth-Key': 'mykey'})
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
f data type (u16, i16, u32, i32, u64, i64, f32 or bit)
c count, if register range not specified
Physical interfaces (PHIs)
delete PHI module file
Deletes PHI module file, if the module is loaded, all its instances should be unloaded first.
DELETE /r/phi-module/gpio_power HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/phi-module/gpio_power -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/phi-module/gpio_power --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/phi-module/gpio_power X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/phi-module/gpio_power', headers={'X-Auth-Key': 'mykey'})
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
GET /r/phi-module/nanoleaf@discover HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/phi-module/nanoleaf@discover -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/phi-module/nanoleaf@discover --header="X-Auth-Key: mykey"
http http://localhost:8812/r/phi-module/nanoleaf@discover X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi-module/nanoleaf@discover', headers={'X-Auth-Key': 'mykey'})
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.
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 -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 -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"}'
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
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'})
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
GET /r/phi-module/vrtrelay HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/phi-module/vrtrelay -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/phi-module/vrtrelay --header="X-Auth-Key: mykey"
http http://localhost:8812/r/phi-module/vrtrelay X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi-module/vrtrelay', headers={'X-Auth-Key': 'mykey'})
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
GET /r/phi-module/vrtrelay?help=cfg HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' -H "X-Auth-Key: mykey"
wget -S -O- 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' --header="X-Auth-Key: mykey"
http 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi-module/vrtrelay?help=cfg', headers={'X-Auth-Key': 'mykey'})
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
GET /r/phi/test1@ports HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/phi/test1@ports -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/phi/test1@ports --header="X-Auth-Key: mykey"
http http://localhost:8812/r/phi/test1@ports X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi/test1@ports', headers={'X-Auth-Key': 'mykey'})
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
GET /r/phi-module HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/phi-module -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/phi-module --header="X-Auth-Key: mykey"
http http://localhost:8812/r/phi-module X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi-module', headers={'X-Auth-Key': 'mykey'})
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
get loaded PHI information
GET /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/phi/test1 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/phi/test1 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/phi/test1 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi/test1', headers={'X-Auth-Key': 'mykey'})
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": {
"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": "test1",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test1",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
}
Parameters:
API Key API key with master permissions
list loaded PHIs
GET /r/phi HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/phi -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/phi --header="X-Auth-Key: mykey"
http http://localhost:8812/r/phi X-Auth-Key:mykey
requests.get('http://localhost:8812/r/phi', headers={'X-Auth-Key': 'mykey'})
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.
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 -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 -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}'
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
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})
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
push state to PHI module
Allows to perform update of PHI ports by external application.
If called as RESTful, the whole request body is used as a payload (except fields “k”, “save”, “kind” and “method”, which are reserved)
POST /r/phi/test1/state HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "1": 1, "2": 0, "3": 1 }
curl -i -X POST http://localhost:8812/r/phi/test1/state -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"1": 1, "2": 0, "3": 1}'
wget -S -O- http://localhost:8812/r/phi/test1/state --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"1": 1, "2": 0, "3": 1}'
echo '{
"1": 1,
"2": 0,
"3": 1
}' | http POST http://localhost:8812/r/phi/test1/state Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/phi/test1/state', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'1': 1, '2': 0, '3': 1})
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 or a key with the write permission on “phi” group
set PHI configuration property
appends property to PHI configuration and reloads module
PATCH /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "default_status": 1 }
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 -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}'
echo '{
"default_status": 1,
"save": true
}' | http PATCH http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/phi/test1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'default_status': 1, 'save': True})
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.
POST /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "self", "method": "test" }
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 -S -O- http://localhost:8812/r/phi/test1 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"c": "self", "method": "test"}'
echo '{
"c": "self",
"method": "test"
}' | http POST http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/phi/test1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'c': 'self', 'method': 'test'})
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.
DELETE /r/phi/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/phi/test2 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/phi/test2 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/phi/test2 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/phi/test2', headers={'X-Auth-Key': 'mykey'})
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.
PUT /r/phi-module/gpio_button HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "<MODULE_CONTENT>" }
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 -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>"}'
echo '{
"c": "<MODULE_CONTENT>"
}' | http PUT http://localhost:8812/r/phi-module/gpio_button Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/phi-module/gpio_button', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'c': '<MODULE_CONTENT>'})
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.
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 -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 -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"}'
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
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'})
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
GET /r/lpi-module/multistep HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/lpi-module/multistep -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/lpi-module/multistep --header="X-Auth-Key: mykey"
http http://localhost:8812/r/lpi-module/multistep X-Auth-Key:mykey
requests.get('http://localhost:8812/r/lpi-module/multistep', headers={'X-Auth-Key': 'mykey'})
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
GET /r/lpi-module/multistep?help=cfg HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET 'http://localhost:8812/r/lpi-module/multistep?help=cfg' -H "X-Auth-Key: mykey"
wget -S -O- 'http://localhost:8812/r/lpi-module/multistep?help=cfg' --header="X-Auth-Key: mykey"
http 'http://localhost:8812/r/lpi-module/multistep?help=cfg' X-Auth-Key:mykey
requests.get('http://localhost:8812/r/lpi-module/multistep?help=cfg', headers={'X-Auth-Key': 'mykey'})
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
GET /r/lpi-module HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/lpi-module -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/lpi-module --header="X-Auth-Key: mykey"
http http://localhost:8812/r/lpi-module X-Auth-Key:mykey
requests.get('http://localhost:8812/r/lpi-module', headers={'X-Auth-Key': 'mykey'})
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
GET /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/driver/test2.my -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/driver/test2.my --header="X-Auth-Key: mykey"
http http://localhost:8812/r/driver/test2.my X-Auth-Key:mykey
requests.get('http://localhost:8812/r/driver/test2.my', headers={'X-Auth-Key': 'mykey'})
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
GET /r/driver HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/driver -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/driver --header="X-Auth-Key: mykey"
http http://localhost:8812/r/driver X-Auth-Key:mykey
requests.get('http://localhost:8812/r/driver', headers={'X-Auth-Key': 'mykey'})
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.
PUT /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "multistep" }
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 -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"}'
echo '{
"m": "multistep"
}' | http PUT http://localhost:8812/r/driver/test2.my Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/driver/test2.my', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'m': 'multistep'})
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
PATCH /r/driver/test1.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "bose": 1 }
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 -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}'
echo '{
"bose": 1,
"save": true
}' | http PATCH http://localhost:8812/r/driver/test1.my Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/driver/test1.my', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'bose': 1, 'save': True})
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.
DELETE /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/driver/test2.my -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/driver/test2.my --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/driver/test2.my X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/driver/test2.my', headers={'X-Auth-Key': 'mykey'})
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
Data pullers
Get data puller
GET /r/datapuller/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/datapuller/test -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/datapuller/test --header="X-Auth-Key: mykey"
http http://localhost:8812/r/datapuller/test X-Auth-Key:mykey
requests.get('http://localhost:8812/r/datapuller/test', headers={'X-Auth-Key': 'mykey'})
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
{
"active": true,
"cmd": "/opt/dp/1.sh",
"name": "test"
}
Parameters:
API Key API key with master permissions
Returns:
Data puller info
List data pullers
GET /r/datapuller HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/datapuller -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/datapuller --header="X-Auth-Key: mykey"
http http://localhost:8812/r/datapuller X-Auth-Key:mykey
requests.get('http://localhost:8812/r/datapuller', headers={'X-Auth-Key': 'mykey'})
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
[
{
"active": true,
"cmd": "/opt/dp/1.sh",
"name": "test"
}
]
Parameters:
API Key API key with master permissions
Returns:
List of all configured data pullers
Restart data puller
POST /r/datapuller/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "cmd": "restart" }
curl -i -X POST http://localhost:8812/r/datapuller/test -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"cmd": "restart"}'
wget -S -O- http://localhost:8812/r/datapuller/test --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"cmd": "restart"}'
echo '{
"cmd": "restart"
}' | http POST http://localhost:8812/r/datapuller/test Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/datapuller/test', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'cmd': 'restart'})
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
Start data puller
POST /r/datapuller/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "cmd": "start" }
curl -i -X POST http://localhost:8812/r/datapuller/test -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"cmd": "start"}'
wget -S -O- http://localhost:8812/r/datapuller/test --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"cmd": "start"}'
echo '{
"cmd": "start"
}' | http POST http://localhost:8812/r/datapuller/test Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/datapuller/test', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'cmd': 'start'})
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
Stop data puller
POST /r/datapuller/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "cmd": "stop" }
curl -i -X POST http://localhost:8812/r/datapuller/test -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"cmd": "stop"}'
wget -S -O- http://localhost:8812/r/datapuller/test --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"cmd": "stop"}'
echo '{
"cmd": "stop"
}' | http POST http://localhost:8812/r/datapuller/test Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/datapuller/test', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'cmd': 'stop'})
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
create data puller
Creates data puller with the specified configuration.
Parameters:
API Key API key with master permissions
i data puller id
c data puller command
Optionally:
t data puller timeout (in seconds, default: default timeout)
e event timeout (default: none)
save save datapuller config after creation
Returns:
If datapuller with the selected ID is already created, error is not returned and datapuller is recreated.
destroy data puller
Creates data puller with the specified configuration.
Parameters:
API Key API key with master permissions
i data puller id
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.
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 -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 -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"}'
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
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'})
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.
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 -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 -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}'
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
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})
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
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
GET /r/device-tpl HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/device-tpl -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/device-tpl --header="X-Auth-Key: mykey"
http http://localhost:8812/r/device-tpl X-Auth-Key:mykey
requests.get('http://localhost:8812/r/device-tpl', headers={'X-Auth-Key': 'mykey'})
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.
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 -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 -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}'
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
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})
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.
GET /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/cvar/test -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/cvar/test --header="X-Auth-Key: mykey"
http http://localhost:8812/r/cvar/test X-Auth-Key:mykey
requests.get('http://localhost:8812/r/cvar/test', headers={'X-Auth-Key': 'mykey'})
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
PUT /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "some_value" }
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 -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"}'
echo '{
"v": "some_value"
}' | http PUT http://localhost:8812/r/cvar/test Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/cvar/test', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'v': 'some_value'})
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 can 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.
PUT /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": 1, "t": 15 }
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 -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}'
echo '{
"e": 1,
"t": 15
}' | http PUT http://localhost:8812/r/lock/mylock1 Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/lock/mylock1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'e': 1, 't': 15})
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
GET /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/lock/mylock1 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/lock/mylock1 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/lock/mylock1', headers={'X-Auth-Key': 'mykey'})
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.
DELETE /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/lock/mylock1 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/lock/mylock1 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/lock/mylock1', headers={'X-Auth-Key': 'mykey'})
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.
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 -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 -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"}'
echo '{
"m": "local file system is full"
}' | http POST http://localhost:8812/r/log/warning Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/log/warning', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'m': 'local file system is full'})
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.
GET /r/log/warning?t=3600&n=3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET 'http://localhost:8812/r/log/warning?t=3600&n=3' -H "X-Auth-Key: mykey"
wget -S -O- 'http://localhost:8812/r/log/warning?t=3600&n=3' --header="X-Auth-Key: mykey"
http 'http://localhost:8812/r/log/warning?t=3600&n=3' X-Auth-Key:mykey
requests.get('http://localhost:8812/r/log/warning?t=3600&n=3', headers={'X-Auth-Key': 'mykey'})
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
x regex pattern filter
rotate log file
Deprecated, not required since 3.3.0
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "log_rotate" }
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 -S -O- http://localhost:8812/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "log_rotate"}'
echo '{
"method": "log_rotate"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/core', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'log_rotate'})
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
get API call log
API call with master permission returns all records requested
API call with other API key returns records for the specified key only
API call with an authentication token returns records for the current authorized user
GET /r/core@apilog HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/core@apilog -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/core@apilog --header="X-Auth-Key: mykey"
http http://localhost:8812/r/core@apilog X-Auth-Key:mykey
requests.get('http://localhost:8812/r/core@apilog', headers={'X-Auth-Key': 'mykey'})
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
[
{
"auth": "key",
"func": "login",
"gw": "http",
"id": "a4ac6da7-2fa8-4938-8613-48e6495158b1",
"ip": "127.0.0.1",
"ki": "operator",
"params": "{\"u\":\"ttt\",\"p\":\"<hidden>\"}",
"status": "OK",
"t": 1596055098.3651853,
"tf": 1596055098.3837607,
"u": "ttt",
"utp": null
},
{
"auth": "key",
"func": "list_key_props",
"gw": "http",
"id": "35685960-cc2f-4fb6-8efc-c4ebca8bf9b5",
"ip": "127.0.0.1",
"ki": "masterkey",
"params": "{\"i\":\"operator\"}",
"status": "OK",
"t": 1596055125.9569867,
"tf": 1596055125.9690392,
"u": null,
"utp": null
},
{
"auth": "key",
"func": "action_toggle",
"gw": "http",
"id": "1bdc23da-95a1-4b41-b354-3f3c62e24405",
"ip": "127.0.0.1",
"ki": "masterkey",
"params": "{\"i\":\"unit:light/hall\",\"p\":null,\"w\":null,\"q\":null,\"u\":null}",
"status": "OK",
"t": 1596055185.7343063,
"tf": 1596055185.7551231,
"u": null,
"utp": null
}
]
Parameters:
API Key any valid API key
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)
n records limit
t time format (“iso” or “raw” for unix timestamp, default is “raw”)
f record filter (requires API key with master permission)
Returns:
List of API calls
Note: API call params are returned as string and can be invalid JSON data as they’re always truncated to 512 symbols in log database
Record filter should be specified either as string (k1=val1,k2=val2) or as a dict. Valid fields are:
gw: filter by API gateway
ip: filter by caller IP
auth: filter by authentication type
u: filter by user
utp: filter by user type
ki: filter by API key ID
func: filter by API function
params: filter by API call params (matches if field contains value)
status: filter by API call status
API keys
create API key
API keys are defined statically in EVA registry config/<controller>/apikeys tree or can be created with API and stored in the user database.
Keys with the master permission can not be created.
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 -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 -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}'
echo '{
"allow": "cmd",
"save": true,
"sysfunc": true
}' | http PUT http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/key/testkey2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'allow': 'cmd', 'save': True, 'sysfunc': True})
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
DELETE /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/key/testkey2 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/key/testkey2 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/key/testkey2', headers={'X-Auth-Key': 'mykey'})
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 EVA registry can not be managed with API.
GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/key/testkey2 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/key/testkey2 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/key/testkey2', headers={'X-Auth-Key': 'mykey'})
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
GET /r/key HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/key -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/key --header="X-Auth-Key: mykey"
http http://localhost:8812/r/key X-Auth-Key:mykey
requests.get('http://localhost:8812/r/key', headers={'X-Auth-Key': 'mykey'})
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
POST /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "regenerate" }
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 -S -O- http://localhost:8812/r/key/testkey2 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "regenerate"}'
echo '{
"method": "regenerate"
}' | http POST http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/key/testkey2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'regenerate'})
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
PATCH /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true }
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 -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}'
echo '{
"save": true,
"sysfunc": true
}' | http PATCH http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/key/testkey2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'save': True, 'sysfunc': True})
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
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "masterkey" }
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 -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --body-data='{"a": "masterkey"}'
echo '{
"a": "masterkey"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/user/test2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'a': 'masterkey'})
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) or multiple keys, comma separated
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.
PUT /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "verysecretpassword", "a": "testkey" }
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 -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"}'
echo '{
"a": "testkey",
"p": "verysecretpassword"
}' | http PUT http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
requests.put('http://localhost:8812/r/user/test2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'a': 'testkey', 'p': 'verysecretpassword'})
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
DELETE /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/user/test2 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/user/test2 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/user/test2 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/user/test2', headers={'X-Auth-Key': 'mykey'})
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
GET /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/user/test2 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/user/test2 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/user/test2 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/user/test2', headers={'X-Auth-Key': 'mykey'})
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
GET /r/user HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/user -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/user --header="X-Auth-Key: mykey"
http http://localhost:8812/r/user X-Auth-Key:mykey
requests.get('http://localhost:8812/r/user', headers={'X-Auth-Key': 'mykey'})
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
Either master key and user login must be specified or a user must be logged in and a session token used
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "qwerty" }
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 -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --body-data='{"p": "qwerty"}'
echo '{
"p": "qwerty"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/user/test2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'p': 'qwerty'})
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 master key or token
p new password
List active session tokens
Parameters:
API Key API key with master permissions
Drop session token(s)
Parameters:
API Key API key with master permissions
a session token or
u user name or
i API key id
Notifier management
disable notifier
Note
The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": false }
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 -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}'
echo '{
"enabled": false
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'enabled': False})
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.
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": true }
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 -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}'
echo '{
"enabled": true
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'enabled': True})
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
GET /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/notifier/eva_1 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/notifier/eva_1 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/notifier/eva_1 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/notifier/eva_1', headers={'X-Auth-Key': 'mykey'})
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
GET /r/notifier HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/notifier -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/notifier --header="X-Auth-Key: mykey"
http http://localhost:8812/r/notifier X-Auth-Key:mykey
requests.get('http://localhost:8812/r/notifier', headers={'X-Auth-Key': 'mykey'})
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
restart notifier
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.
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 -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 -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"}'
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
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'})
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 (plain text or base64-encoded)
b if True - put binary file (decode base64)
set file exec permission
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 -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 -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}'
echo '{
"e": true
}' | http PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
requests.patch('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'e': True})
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
DELETE /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H "X-Auth-Key: mykey"
wget -S -O- --method=DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header="X-Auth-Key: mykey"
http DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
requests.delete('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={'X-Auth-Key': 'mykey'})
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
GET /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header="X-Auth-Key: mykey"
http http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
requests.get('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={'X-Auth-Key': 'mykey'})
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
b if True - force getting binary file (base64-encode content)
Core scripts
List MQTT topics core scripts react on
GET /r/corescript/mqtt-topics HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl -i -X GET http://localhost:8812/r/corescript/mqtt-topics -H "X-Auth-Key: mykey"
wget -S -O- http://localhost:8812/r/corescript/mqtt-topics --header="X-Auth-Key: mykey"
http http://localhost:8812/r/corescript/mqtt-topics X-Auth-Key:mykey
requests.get('http://localhost:8812/r/corescript/mqtt-topics', headers={'X-Auth-Key': 'mykey'})
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
[
{
"qos": 2,
"topic": "eva_1:cluster/#"
},
{
"qos": 2,
"topic": "test/test2"
},
{
"qos": 1,
"topic": "ttt/ttt"
}
]
Parameters:
API Key API key with master permissions
Reload core scripts if some was added or deleted
POST /r/corescript HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "reload" }
curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "reload"}'
wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "reload"}'
echo '{
"method": "reload"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'reload'})
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
Subscribe core scripts to MQTT topic
The method subscribes core scripts to topic of default MQTT notifier (eva_1). To specify another notifier, set topic as <notifer_id>:<topic>
POST /r/corescript HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "q": 2, "method": "mqtt-subscribe", "t": "some/test/topic2" }
curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "mqtt-subscribe", "q": 2, "t": "some/test/topic2"}'
wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "mqtt-subscribe", "q": 2, "t": "some/test/topic2"}'
echo '{
"method": "mqtt-subscribe",
"q": 2,
"t": "some/test/topic2"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'mqtt-subscribe', 'q': 2, 't': 'some/test/topic2'})
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
t MQTT topic (“+” and “#” masks are supported)
q MQTT topic QoS
save save core script config after modification
Unsubscribe core scripts from MQTT topic
POST /r/corescript HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "mqtt-unsubscribe", "t": "some/test/topic2" }
curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "mqtt-unsubscribe", "t": "some/test/topic2"}'
wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "mqtt-unsubscribe", "t": "some/test/topic2"}'
echo '{
"method": "mqtt-unsubscribe",
"t": "some/test/topic2"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey
requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'mqtt-unsubscribe', 't': 'some/test/topic2'})
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
t MQTT topic (“+” and “#” masks are allowed)
save save core script config after modification
Registry management
Safely purge registry database
Clears registry trash and invalid files. Keeps broken keys
Parameters:
API Key API key with sysfunc=yes permissions