UC API
Universal Controller API is used to control and manage units and sensors
This document describes API methods for direct and JSON RPC calls. For RESTful API look UC RESTful API.
API basics
Standard API (direct method calling)
UC API functions are called through URL request
http://<ip_address:8812>/uc-api/function
If SSL is allowed in the controller configuration file, you can also use https calls.
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Standard API responses
Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.
API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.
Standard responses in status/body:
- 200 OK { “result”: “OK” } API call completed successfully.
Standard error responses in status:
- 400 Bad Request Invalid request params
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found method or resource/object doesn’t exist
- 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
In case API function has been failed, response body will contain JSON data with _error field, which contains error message.
{
"_error": "unable to add object, already present",
"result": "ERROR"
}
JSON RPC
Additionally, API supports JSON RPC 2.0 protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” }). There’s no error result, as JSON RPC sends errors in “error” field.
If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.
Note
JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.
JSON RPC API URL:
http://<ip_address:8812>/jrpc
JSON RPC error responses
JSON RPC calls return error codes equal to the codes of EVA API Client:
- 1 the item or resource is not found
- 2 access is denied with the set API key
- 6 Attempt to call undefined API method/function
- 10 API function failed (all errors not listed here fall within this category)
- 11 API function is called with invalid params
- 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
- 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
- 14 the method is not implemented in/for requested resource
Response field “message” may contain additional information about error.
Contents
- UC API
- API basics
- General functions
- Item functions
- action - unit control action
- action_toggle - toggle unit status
- disable_actions - disable unit actions
- enable_actions - enable unit actions
- groups - get item group list
- kill - kill unit actions
- q_clean - clean action queue of unit
- result - get action status
- start_item_maintenance - start item maintenance mode
- state - get item state
- state_history - get item state history
- stop_item_maintenance - stop item maintenance mode
- terminate - terminate action execution
- update - update the status and value of the item
- Item management
- list - list items
- create - create new item
- create_mu - create multi-update
- create_sensor - create new sensor
- create_unit - create new unit
- destroy - delete item or group
- get_config - get item configuration
- list_props - list item properties
- save_config - save item configuration
- set_prop - set item property
- clone - clone item
- clone_group - clone group
- 1-Wire bus via OWFS
- Modbus ports
- create_modbus_port - create virtual Modbus port
- destroy_modbus_port - delete virtual Modbus port
- get_modbus_port - get virtual Modbus port configuration
- list_modbus_ports - list virtual Modbus ports
- read_modbus_port - read Modbus register(s) from remote slave
- test_modbus_port - test virtual Modbus port
- write_modbus_port - write Modbus register(s) to remote slave
- get_modbus_slave_data - get Modbus slave data
- Physical interfaces (PHIs)
- exec_phi - execute additional PHI commands
- get_phi_ports - get list of PHI ports
- list_phi - list loaded PHIs
- list_phi_mods - get list of available PHI modules
- load_phi - load PHI module
- modhelp_phi - get PHI usage help
- modinfo_phi - get PHI module info
- phi_discover - discover installed equipment supported by PHI module
- put_phi_mod - upload PHI module
- set_phi_prop - set PHI configuration property
- test_phi - test PHI
- unlink_phi_mod - delete PHI module file
- unload_phi - unload PHI
- LPI and drivers
- assign_driver - assign driver to item
- get_driver - get loaded driver information
- list_drivers - list loaded drivers
- list_lpi_mods - get list of available LPI modules
- load_driver - load a driver
- modhelp_lpi - get LPI usage help
- modinfo_lpi - get LPI module info
- set_driver_prop - set driver (LPI) configuration property
- unload_driver - unload driver
- Devices
General functions
test - test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
POST /uc-api/test HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/test -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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",
"result": "OK",
"setup_mode": false,
"system": "mws1-v1",
"time": 1552867566.8738406,
"uptime": 990,
"version": "3.2.0"
}
Parameters:
- k any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
login - log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /uc-api/login HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8812/uc-api/login -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8812/uc-api/login --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8812/uc-api/login Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/login', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
logout - log out and purge authentication token
Purges authentication token
http
POST /uc-api/logout HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7" }
curl
curl -i -X POST http://localhost:8812/uc-api/logout -H 'Content-Type: application/json' --data-raw '{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
wget
wget -S -O- http://localhost:8812/uc-api/logout --header='Content-Type: application/json' --post-data='{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
httpie
echo '{
"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
}' | http POST http://localhost:8812/uc-api/logout Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/logout', headers={
'Content-Type': 'application/json',
}, json={
'k': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid token
Item functions
action - unit control action
The call is considered successful when action is put into the action queue of selected unit.
http
POST /uc-api/action HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "s": 1 }
curl
curl -i -X POST http://localhost:8812/uc-api/action -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "s": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/action --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "s": 1}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"s": 1
}' | http POST http://localhost:8812/uc-api/action Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/action', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
's': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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"
}
Parameters:
- k valid API key
- i unit id
Optionally:
- s desired unit status
- v desired unit value
- w wait for the completion for the specified number of seconds
- u action UUID (will be auto generated if none specified)
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
action_toggle - toggle unit status
Create unit control action to toggle its status (1->0, 0->1)
http
POST /uc-api/action_toggle HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/action_toggle -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/action_toggle --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/action_toggle Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/action_toggle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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.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"
}
Parameters:
- k valid API key
- i unit id
Optionally:
- w wait for the completion for the specified number of seconds
- u action UUID (will be auto generated if none specified)
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
disable_actions - disable unit actions
Disables unit to run and queue new actions.
http
POST /uc-api/disable_actions HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/disable_actions -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/disable_actions --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/disable_actions Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/disable_actions', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
enable_actions - enable unit actions
Enables unit to run and queue new actions.
http
POST /uc-api/enable_actions HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/enable_actions -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/enable_actions --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/enable_actions Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/enable_actions', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
groups - get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
POST /uc-api/groups HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "p": "unit" }
curl
curl -i -X POST http://localhost:8812/uc-api/groups -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "unit"}'
wget
wget -S -O- http://localhost:8812/uc-api/groups --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "unit"}'
httpie
echo '{
"k": "mykey",
"p": "unit"
}' | http POST http://localhost:8812/uc-api/groups Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/groups', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'unit',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k valid API key
- p item type (unit [U] or sensor [S])
kill - kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
http
POST /uc-api/kill HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/kill -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/kill --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/kill Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/kill', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
Returns:
If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)
q_clean - clean action queue of unit
Cancels all queued actions, keeps the current action running.
http
POST /uc-api/q_clean HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/q_clean -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/q_clean --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/q_clean Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/q_clean', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
result - get action status
Checks the result of the action by its UUID or returns the actions for the specified unit.
http
POST /uc-api/result HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/result -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/result --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/result Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/result', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k valid API key
Optionally:
- u action uuid or
- i unit id
- 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
start_item_maintenance - start item maintenance mode
During maintenance mode all item updates are ignored, however actions still can be executed
http
POST /uc-api/start_item_maintenance HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1" }
curl
curl -i -X POST http://localhost:8812/uc-api/start_item_maintenance -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/start_item_maintenance --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey"}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/start_item_maintenance Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/start_item_maintenance', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k masterkey
- i item ID
state - get item state
State of the item or all items of the specified type can be obtained using state command.
http
POST /uc-api/state HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "p": "sensor" }
curl
curl -i -X POST http://localhost:8812/uc-api/state -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "sensor"}'
wget
wget -S -O- http://localhost:8812/uc-api/state --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "sensor"}'
httpie
echo '{
"k": "mykey",
"p": "sensor"
}' | http POST http://localhost:8812/uc-api/state Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/state', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'sensor',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k valid API key
- p item type (unit [U] or sensor [S])
Optionally:
- i item id
- g item group
- full return full state
state_history - get item state history
State history of one item or several items of the specified type can be obtained using state_history command.
If master key is used, method attempt to get stored state for item even if it currently doesn’t present.
http
POST /uc-api/state_history HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1" }
curl
curl -i -X POST http://localhost:8812/uc-api/state_history -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/state_history --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey"}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/state_history Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/state_history', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k valid API key
- a history notifier id (default: db_1)
- i item oids or full ids, list or comma separated
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- 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.
stop_item_maintenance - stop item maintenance mode
http
POST /uc-api/stop_item_maintenance HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1" }
curl
curl -i -X POST http://localhost:8812/uc-api/stop_item_maintenance -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/stop_item_maintenance --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey"}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/stop_item_maintenance Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/stop_item_maintenance', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k masterkey
- i item ID
terminate - terminate action execution
Terminates or cancel the action if it is still queued
http
POST /uc-api/terminate HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/terminate -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/terminate --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/terminate Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/terminate', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- u action uuid or
- i unit id
Returns:
An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)
update - update the status and value of the item
Updates the status and value of the item. This is one of the ways of passive state update, for example with the use of an external controller.
Note
Calling without s and v params will force item to perform passive update requesting its status from update script or driver.
http
POST /uc-api/update HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1", "s": 1, "v": 29.445 }
curl
curl -i -X POST http://localhost:8812/uc-api/update -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey", "s": 1, "v": 29.445}'
wget
wget -S -O- http://localhost:8812/uc-api/update --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey", "s": 1, "v": 29.445}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey",
"s": 1,
"v": 29.445
}' | http POST http://localhost:8812/uc-api/update Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/update', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
's': 1,
'v': 29.445,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i item id
Optionally:
- s item status
- v item value
Item management
list - list items
http
POST /uc-api/list HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "",
"full_id": "tests/sensor1",
"group": "tests",
"id": "sensor1",
"oid": "sensor:tests/sensor1",
"type": "sensor"
},
{
"description": "",
"full_id": "tests/sensor2",
"group": "tests",
"id": "sensor2",
"oid": "sensor:tests/sensor2",
"type": "sensor"
},
{
"description": "",
"full_id": "tests/unit1",
"group": "tests",
"id": "unit1",
"oid": "unit:tests/unit1",
"type": "unit"
},
{
"description": "",
"full_id": "tests/unit3",
"group": "tests",
"id": "unit3",
"oid": "unit:tests/unit3",
"type": "unit"
}
]
Parameters:
- k API key with master permissions
Optionally:
- p filter by item type
- g filter by item group
- x serialize specified item prop(s)
Returns:
the list of all item available
create - create new item
Creates new item.
http
POST /uc-api/create HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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": 0,
"type": "sensor",
"value": "null"
}
Parameters:
- k API key with master permissions
- i item oid (type:group/id)
Optionally:
- g item group
- save save multi-update configuration immediately
create_mu - create multi-update
Creates new multi-update.
http
POST /uc-api/create_mu HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mu:tests/mu1", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_mu -H 'Content-Type: application/json' --data-raw '{"i": "mu:tests/mu1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create_mu --header='Content-Type: application/json' --post-data='{"i": "mu:tests/mu1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "mu:tests/mu1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create_mu Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_mu', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mu:tests/mu1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/mu1",
"group": "tests",
"id": "mu1",
"oid": "mu:tests/mu1",
"status": 0,
"type": "mu",
"value": "null"
}
Parameters:
- k API key with master permissions
- i multi-update id
Optionally:
- g multi-update group
- save save multi-update configuration immediately
create_sensor - create new sensor
Creates new sensor.
http
POST /uc-api/create_sensor HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "tests/sensor5", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_sensor -H 'Content-Type: application/json' --data-raw '{"i": "tests/sensor5", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create_sensor --header='Content-Type: application/json' --post-data='{"i": "tests/sensor5", "k": "mykey", "save": true}'
httpie
echo '{
"i": "tests/sensor5",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create_sensor Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_sensor', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/sensor5',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/sensor5",
"group": "tests",
"id": "sensor5",
"oid": "sensor:tests/sensor5",
"status": 0,
"type": "sensor",
"value": "null"
}
Parameters:
- k API key with master permissions
- i sensor id
Optionally:
- g sensor group
- save save sensor configuration immediately
create_unit - create new unit
Creates new unit.
http
POST /uc-api/create_unit HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "tests/unit1", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_unit -H 'Content-Type: application/json' --data-raw '{"i": "tests/unit1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create_unit --header='Content-Type: application/json' --post-data='{"i": "tests/unit1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "tests/unit1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create_unit Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_unit', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/unit1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": false,
"full_id": "tests/unit1",
"group": "tests",
"id": "unit1",
"nstatus": 0,
"nvalue": "null",
"oid": "unit:tests/unit1",
"status": 0,
"type": "unit",
"value": "null"
}
Parameters:
- k API key with master permissions
- i unit id
Optionally:
- g unit group
- save save unit configuration immediately
destroy - delete item or group
Deletes the item or the group (and all the items in it) from the system.
http
POST /uc-api/destroy HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/destroy -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/destroy --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/destroy Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/destroy', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- g group (either item or group must be specified)
get_config - get item configuration
http
POST /uc-api/get_config HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_config -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_config --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_config Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_config', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/unit1",
"group": "tests",
"id": "unit1",
"oid": "unit:tests/unit1",
"type": "unit"
}
Parameters:
- k API key with master permissions
- i item id
Returns:
complete item configuration
list_props - list item properties
Get all editable parameters of the item confiugration.
http
POST /uc-api/list_props HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_props -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_props --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_props Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_allow_termination": false,
"action_always_exec": false,
"action_driver_config": null,
"action_enabled": true,
"action_exec": null,
"action_queue": 0,
"action_timeout": null,
"auto_off": 0,
"description": "",
"expires": 0,
"location": null,
"mqtt_control": null,
"mqtt_update": null,
"snmp_trap": null,
"status_labels": {
"0": "OFF",
"1": "ON"
},
"term_kill_interval": null,
"update_delay": 0,
"update_driver_config": null,
"update_exec": null,
"update_exec_after_action": false,
"update_if_action": false,
"update_interval": 0,
"update_state_after_action": true,
"update_timeout": null,
"virtual": false
}
Parameters:
- k API key with master permissions
- i item id
save_config - save item configuration
Saves item. configuration on disk (even if it hasn’t been changed)
http
POST /uc-api/save_config HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/save_config -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/save_config --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/save_config Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/save_config', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
set_prop - set item property
Set configuration parameters of the item.
http
POST /uc-api/set_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "p": "action_allow_termination", "v": true }
curl
curl -i -X POST http://localhost:8812/uc-api/set_prop -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "p": "action_allow_termination", "v": true}'
wget
wget -S -O- http://localhost:8812/uc-api/set_prop --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "p": "action_allow_termination", "v": true}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"p": "action_allow_termination",
"v": true
}' | http POST http://localhost:8812/uc-api/set_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/set_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
'p': 'action_allow_termination',
'v': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
clone - clone item
Creates a copy of the item.
http
POST /uc-api/clone HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "n": "unit:tests/clone_of_unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/clone -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "n": "unit:tests/clone_of_unit1"}'
wget
wget -S -O- http://localhost:8812/uc-api/clone --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "n": "unit:tests/clone_of_unit1"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"n": "unit:tests/clone_of_unit1"
}' | http POST http://localhost:8812/uc-api/clone Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/clone', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
'n': 'unit:tests/clone_of_unit1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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_unit1",
"group": "tests",
"id": "clone_of_unit1",
"nstatus": 0,
"nvalue": "null",
"oid": "unit:tests/clone_of_unit1",
"status": 0,
"type": "unit",
"value": "null"
}
Parameters:
- k API key with master permissions
- i item id
- n new item id
Optionally:
- g group for new item
- save save multi-update configuration immediately
clone_group - clone group
Creates a copy of all items from the group.
http
POST /uc-api/clone_group HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "g": "tests", "n": "clone_of_tests" }
curl
curl -i -X POST http://localhost:8812/uc-api/clone_group -H 'Content-Type: application/json' --data-raw '{"g": "tests", "k": "mykey", "n": "clone_of_tests"}'
wget
wget -S -O- http://localhost:8812/uc-api/clone_group --header='Content-Type: application/json' --post-data='{"g": "tests", "k": "mykey", "n": "clone_of_tests"}'
httpie
echo '{
"g": "tests",
"k": "mykey",
"n": "clone_of_tests"
}' | http POST http://localhost:8812/uc-api/clone_group Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/clone_group', headers={
'Content-Type': 'application/json',
}, json={
'g': 'tests',
'k': 'mykey',
'n': 'clone_of_tests',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- g group to clone
- 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
1-Wire bus via OWFS
create_owfs_bus - create OWFS bus
Creates (defines) OWFS bus with the specified configuration.
Parameter “location” (“n”) should contain the connection configuration, e.g. “localhost:4304” for owhttpd or “i2c=/dev/i2c-1:ALL”, “/dev/i2c-0 –w1” for local 1-Wire bus via I2C, depending on type.
http
POST /uc-api/create_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local", "n": "localhost:4304", "l": true, "t": 1, "r": 5, "d": 0.3, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_owfs_bus -H 'Content-Type: application/json' --data-raw '{"d": 0.3, "i": "bus_local", "k": "mykey", "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/create_owfs_bus --header='Content-Type: application/json' --post-data='{"d": 0.3, "i": "bus_local", "k": "mykey", "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'
httpie
echo '{
"d": 0.3,
"i": "bus_local",
"k": "mykey",
"l": true,
"n": "localhost:4304",
"r": 5,
"save": true,
"t": 1
}' | http POST http://localhost:8812/uc-api/create_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'd': 0.3,
'i': 'bus_local',
'k': 'mykey',
'l': True,
'n': 'localhost:4304',
'r': 5,
'save': True,
't': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i bus ID which will be used later in PHI configurations, required
- 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.
destroy_owfs_bus - delete OWFS bus
Deletes (undefines) OWFS bus.
Note
In some cases deleted OWFS bus located on I2C may lock libow library calls, which require controller restart until you can use (create) the same I2C bus again.
http
POST /uc-api/destroy_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/destroy_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/destroy_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/destroy_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/destroy_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i bus ID
get_owfs_bus - get OWFS bus configuration
http
POST /uc-api/get_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.3,
"id": "bus_local",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
}
Parameters:
- k API key with master permissions
- i bus ID
list_owfs_buses - list OWFS buses
http
POST /uc-api/list_owfs_buses HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_owfs_buses -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_owfs_buses --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_owfs_buses Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_owfs_buses', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
scan_owfs_bus - scan OWFS bus
Scan OWFS bus for connected 1-Wire devices.
http
POST /uc-api/scan_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/scan_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/scan_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/scan_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/scan_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- i bus ID
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 - test OWFS bus
Verifies OWFS bus checking library initialization status.
http
POST /uc-api/test_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/test_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i bus ID
Modbus ports
create_modbus_port - create virtual Modbus port
Creates virtual Modbus port with the specified configuration.
Modbus params should contain the configuration of hardware Modbus port. The following hardware port types are supported:
- tcp , udp Modbus protocol implementations for TCP/IP networks. The params should be specified as: <protocol>:<host>[:port], e.g. tcp:192.168.11.11:502
- rtu, ascii, binary Modbus protocol implementations for the local bus connected with USB or serial port. The params should be specified as: <protocol>:<device>:<speed>:<data>:<parity>:<stop> e.g. rtu:/dev/ttyS0:9600:8:E:1
http
POST /uc-api/create_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1", "p": "udp:192.168.33.33:502", "l": true, "t": 0.5, "r": 3, "d": 0.2, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_modbus_port -H 'Content-Type: application/json' --data-raw '{"d": 0.2, "i": "mbp1", "k": "mykey", "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'
wget
wget -S -O- http://localhost:8812/uc-api/create_modbus_port --header='Content-Type: application/json' --post-data='{"d": 0.2, "i": "mbp1", "k": "mykey", "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'
httpie
echo '{
"d": 0.2,
"i": "mbp1",
"k": "mykey",
"l": true,
"p": "udp:192.168.33.33:502",
"r": 3,
"save": true,
"t": 0.5
}' | http POST http://localhost:8812/uc-api/create_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'd': 0.2,
'i': 'mbp1',
'k': 'mykey',
'l': True,
'p': 'udp:192.168.33.33:502',
'r': 3,
'save': True,
't': 0.5,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i virtual port ID which will be used later in PHI configurations, required
- 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.
destroy_modbus_port - delete virtual Modbus port
Deletes virtual Modbus port.
http
POST /uc-api/destroy_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1" }
curl
curl -i -X POST http://localhost:8812/uc-api/destroy_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "mbp1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/destroy_modbus_port --header='Content-Type: application/json' --post-data='{"i": "mbp1", "k": "mykey"}'
httpie
echo '{
"i": "mbp1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/destroy_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/destroy_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mbp1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i virtual port ID
get_modbus_port - get virtual Modbus port configuration
http
POST /uc-api/get_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "mbp1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_modbus_port --header='Content-Type: application/json' --post-data='{"i": "mbp1", "k": "mykey"}'
httpie
echo '{
"i": "mbp1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mbp1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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
}
Parameters:
- k API key with master permissions
- i port ID
list_modbus_ports - list virtual Modbus ports
http
POST /uc-api/list_modbus_ports HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_modbus_ports -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_modbus_ports --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_modbus_ports Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_modbus_ports', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- i virtual port ID
read_modbus_port - read Modbus register(s) from remote slave
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).
Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15
http
POST /uc-api/read_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "h10-12,c5-6", "p": "local", "s": 1 }
curl
curl -i -X POST http://localhost:8812/uc-api/read_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "h10-12,c5-6", "k": "mykey", "p": "local", "s": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/read_modbus_port --header='Content-Type: application/json' --post-data='{"i": "h10-12,c5-6", "k": "mykey", "p": "local", "s": 1}'
httpie
echo '{
"i": "h10-12,c5-6",
"k": "mykey",
"p": "local",
"s": 1
}' | http POST http://localhost:8812/uc-api/read_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/read_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'h10-12,c5-6',
'k': 'mykey',
'p': 'local',
's': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- p Modbus virtual port
- s Slave ID
- i Modbus register(s)
Optionally:
- t max allowed timeout for the operation
test_modbus_port - test virtual Modbus port
Verifies virtual Modbus port by calling connect() Modbus client method.
Note
As Modbus UDP doesn’t require a port to be connected, API call always returns success unless the port is locked.
http
POST /uc-api/test_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1" }
curl
curl -i -X POST http://localhost:8812/uc-api/test_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "mbp1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test_modbus_port --header='Content-Type: application/json' --post-data='{"i": "mbp1", "k": "mykey"}'
httpie
echo '{
"i": "mbp1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mbp1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i virtual port ID
write_modbus_port - write Modbus register(s) to remote slave
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, c - coil).
http
POST /uc-api/write_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "h10", "p": "local", "s": 1, "v": 2522 }
curl
curl -i -X POST http://localhost:8812/uc-api/write_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "h10", "k": "mykey", "p": "local", "s": 1, "v": 2522}'
wget
wget -S -O- http://localhost:8812/uc-api/write_modbus_port --header='Content-Type: application/json' --post-data='{"i": "h10", "k": "mykey", "p": "local", "s": 1, "v": 2522}'
httpie
echo '{
"i": "h10",
"k": "mykey",
"p": "local",
"s": 1,
"v": 2522
}' | http POST http://localhost:8812/uc-api/write_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/write_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'h10',
'k': 'mykey',
'p': 'local',
's': 1,
'v': 2522,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- p Modbus virtual port
- s Slave ID
- i Modbus register address
- v register value(s) (integer or hex or list)
- z if True, use 0x05-06 commands (write single register/coil)
Optionally:
- t max allowed timeout for the operation
get_modbus_slave_data - get Modbus slave data
Get data from Modbus slave memory space
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).
Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15
http
POST /uc-api/get_modbus_slave_data HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "h1000-1005,c10-15" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_modbus_slave_data -H 'Content-Type: application/json' --data-raw '{"i": "h1000-1005,c10-15", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_modbus_slave_data --header='Content-Type: application/json' --post-data='{"i": "h1000-1005,c10-15", "k": "mykey"}'
httpie
echo '{
"i": "h1000-1005,c10-15",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_modbus_slave_data Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_modbus_slave_data', headers={
'Content-Type': 'application/json',
}, json={
'i': 'h1000-1005,c10-15',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- i Modbus register(s)
Physical interfaces (PHIs)
exec_phi - execute additional PHI commands
Execute PHI command and return execution result (as-is). help command returns all available commands.
http
POST /uc-api/exec_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "c": "update_firmware", "a": "/opt/firmware/fw.dat" }
curl
curl -i -X POST http://localhost:8812/uc-api/exec_phi -H 'Content-Type: application/json' --data-raw '{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/exec_phi --header='Content-Type: application/json' --post-data='{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "i": "test1", "k": "mykey"}'
httpie
echo '{
"a": "/opt/firmware/fw.dat",
"c": "update_firmware",
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/exec_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/exec_phi', headers={
'Content-Type': 'application/json',
}, json={
'a': '/opt/firmware/fw.dat',
'c': 'update_firmware',
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"output": "not implemented"
}
Parameters:
- k API key with master permissions
- i PHI id
- c command to exec
- a command argument
get_phi_ports - get list of PHI ports
http
POST /uc-api/get_phi_ports HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_phi_ports -H 'Content-Type: application/json' --data-raw '{"i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_phi_ports --header='Content-Type: application/json' --post-data='{"i": "test1", "k": "mykey"}'
httpie
echo '{
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_phi_ports Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_phi_ports', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- i PHI id
list_phi - list loaded PHIs
http
POST /uc-api/list_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_phi -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_phi --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_phi', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- full get exntended information
list_phi_mods - get list of available PHI modules
http
POST /uc-api/list_phi_mods HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_phi_mods -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_phi_mods --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_phi_mods Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_phi_mods', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
load_phi - load PHI module
Loads Physical Interface.
http
POST /uc-api/load_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "m": "vrtrelay", "c": "default_status=0", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/load_phi -H 'Content-Type: application/json' --data-raw '{"c": "default_status=0", "i": "test1", "k": "mykey", "m": "vrtrelay", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/load_phi --header='Content-Type: application/json' --post-data='{"c": "default_status=0", "i": "test1", "k": "mykey", "m": "vrtrelay", "save": true}'
httpie
echo '{
"c": "default_status=0",
"i": "test1",
"k": "mykey",
"m": "vrtrelay",
"save": true
}' | http POST http://localhost:8812/uc-api/load_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/load_phi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'default_status=0',
'i': 'test1',
'k': 'mykey',
'm': 'vrtrelay',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- i PHI ID
- m PHI module
Optionally:
- c PHI configuration
- save save driver configuration after successful call
modhelp_phi - get PHI usage help
http
POST /uc-api/modhelp_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "vrtrelay", "c": "cfg" }
curl
curl -i -X POST http://localhost:8812/uc-api/modhelp_phi -H 'Content-Type: application/json' --data-raw '{"c": "cfg", "k": "mykey", "m": "vrtrelay"}'
wget
wget -S -O- http://localhost:8812/uc-api/modhelp_phi --header='Content-Type: application/json' --post-data='{"c": "cfg", "k": "mykey", "m": "vrtrelay"}'
httpie
echo '{
"c": "cfg",
"k": "mykey",
"m": "vrtrelay"
}' | http POST http://localhost:8812/uc-api/modhelp_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modhelp_phi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'cfg',
'k': 'mykey',
'm': 'vrtrelay',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- m PHI module name (without .py extension)
- c help context (cfg, get or set)
modinfo_phi - get PHI module info
http
POST /uc-api/modinfo_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "vrtrelay" }
curl
curl -i -X POST http://localhost:8812/uc-api/modinfo_phi -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "vrtrelay"}'
wget
wget -S -O- http://localhost:8812/uc-api/modinfo_phi --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "vrtrelay"}'
httpie
echo '{
"k": "mykey",
"m": "vrtrelay"
}' | http POST http://localhost:8812/uc-api/modinfo_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modinfo_phi', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'vrtrelay',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- m PHI module name (without .py extension)
phi_discover - discover installed equipment supported by PHI module
http
POST /uc-api/phi_discover HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "nanoleaf" }
curl
curl -i -X POST http://localhost:8812/uc-api/phi_discover -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "nanoleaf"}'
wget
wget -S -O- http://localhost:8812/uc-api/phi_discover --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "nanoleaf"}'
httpie
echo '{
"k": "mykey",
"m": "nanoleaf"
}' | http POST http://localhost:8812/uc-api/phi_discover Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/phi_discover', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'nanoleaf',
})
response
HTTP/1.1 200 OK
Content-Type: application/json
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- m PHI module name (without .py extension)
Optionally:
- x interface to perform discover on
- w max time for the operation
put_phi_mod - upload PHI module
Allows to upload new PHI module to xc/drivers/phi folder.
http
POST /uc-api/put_phi_mod HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "gpio_button", "c": "<MODULE_CONTENT>" }
curl
curl -i -X POST http://localhost:8812/uc-api/put_phi_mod -H 'Content-Type: application/json' --data-raw '{"c": "<MODULE_CONTENT>", "k": "mykey", "m": "gpio_button"}'
wget
wget -S -O- http://localhost:8812/uc-api/put_phi_mod --header='Content-Type: application/json' --post-data='{"c": "<MODULE_CONTENT>", "k": "mykey", "m": "gpio_button"}'
httpie
echo '{
"c": "<MODULE_CONTENT>",
"k": "mykey",
"m": "gpio_button"
}' | http POST http://localhost:8812/uc-api/put_phi_mod Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/put_phi_mod', headers={
'Content-Type': 'application/json',
}, json={
'c': '<MODULE_CONTENT>',
'k': 'mykey',
'm': 'gpio_button',
})
response
HTTP/1.1 200 OK
Content-Type: application/json
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
{
"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:
- k API key with master permissions
- m PHI module name (without .py extension)
- c module content
Optionally:
- force overwrite PHI module file if exists
set_phi_prop - set PHI configuration property
appends property to PHI configuration and reloads module
http
POST /uc-api/set_phi_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "p": "default_status", "v": 1, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/set_phi_prop -H 'Content-Type: application/json' --data-raw '{"i": "test1", "k": "mykey", "p": "default_status", "save": true, "v": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/set_phi_prop --header='Content-Type: application/json' --post-data='{"i": "test1", "k": "mykey", "p": "default_status", "save": true, "v": 1}'
httpie
echo '{
"i": "test1",
"k": "mykey",
"p": "default_status",
"save": true,
"v": 1
}' | http POST http://localhost:8812/uc-api/set_phi_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/set_phi_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1',
'k': 'mykey',
'p': 'default_status',
'save': True,
'v': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i PHI ID
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
test_phi - test PHI
Get PHI test result (as-is). All PHIs respond to self command, help command returns all available test commands.
http
POST /uc-api/test_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "c": "self" }
curl
curl -i -X POST http://localhost:8812/uc-api/test_phi -H 'Content-Type: application/json' --data-raw '{"c": "self", "i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test_phi --header='Content-Type: application/json' --post-data='{"c": "self", "i": "test1", "k": "mykey"}'
httpie
echo '{
"c": "self",
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test_phi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'self',
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"output": "OK"
}
Parameters:
- k API key with master permissions
- m PHI id
- c test command
unlink_phi_mod - delete PHI module file
Deletes PHI module file, if the module is loaded, all its instances should be unloaded first.
http
POST /uc-api/unlink_phi_mod HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "gpio_button" }
curl
curl -i -X POST http://localhost:8812/uc-api/unlink_phi_mod -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "gpio_button"}'
wget
wget -S -O- http://localhost:8812/uc-api/unlink_phi_mod --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "gpio_button"}'
httpie
echo '{
"k": "mykey",
"m": "gpio_button"
}' | http POST http://localhost:8812/uc-api/unlink_phi_mod Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/unlink_phi_mod', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'gpio_button',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- m PHI module name (without .py extension)
unload_phi - unload PHI
Unloads PHI. PHI should not be used by any driver (except default, but the driver should not be in use by any item).
If driver <phi_id.default> (which’s loaded automatically with PHI) is present, it will be unloaded as well.
http
POST /uc-api/unload_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1" }
curl
curl -i -X POST http://localhost:8812/uc-api/unload_phi -H 'Content-Type: application/json' --data-raw '{"i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/unload_phi --header='Content-Type: application/json' --post-data='{"i": "test1", "k": "mykey"}'
httpie
echo '{
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/unload_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/unload_phi', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i PHI ID
LPI and drivers
assign_driver - assign driver to item
Sets the specified driver to item, automatically updating item props:
- action_driver_config,**update_driver_config** to the specified configuration * action_exec, update_exec to do all operations via driver function calls (sets both to |<driver_id>)
To unassign driver, set driver ID to empty/null.
http
POST /uc-api/assign_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "d": "test1.my", "c": "port=5" }
curl
curl -i -X POST http://localhost:8812/uc-api/assign_driver -H 'Content-Type: application/json' --data-raw '{"c": "port=5", "d": "test1.my", "i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/assign_driver --header='Content-Type: application/json' --post-data='{"c": "port=5", "d": "test1.my", "i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"c": "port=5",
"d": "test1.my",
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/assign_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/assign_driver', headers={
'Content-Type': 'application/json',
}, json={
'c': 'port=5',
'd': 'test1.my',
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k masterkey
- i item ID
- 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_driver - get loaded driver information
http
POST /uc-api/get_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1.my" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_driver -H 'Content-Type: application/json' --data-raw '{"i": "test1.my", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_driver --header='Content-Type: application/json' --post-data='{"i": "test1.my", "k": "mykey"}'
httpie
echo '{
"i": "test1.my",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_driver', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1.my',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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": "test1.my",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"lpi_id": "my",
"mod": "multistep",
"oid": "driver:uc/mws1-v1/test1.my",
"phi": {
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 1
},
"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"
},
"phi_id": "test1",
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- i PHI ID
list_drivers - list loaded drivers
http
POST /uc-api/list_drivers HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_drivers -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_drivers --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_drivers Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_drivers', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- full get exntended information
list_lpi_mods - get list of available LPI modules
http
POST /uc-api/list_lpi_mods HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_lpi_mods -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_lpi_mods --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_lpi_mods Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_lpi_mods', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
load_driver - load a driver
Loads a driver, combining previously loaded PHI and chosen LPI module.
http
POST /uc-api/load_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "my", "m": "multistep", "p": "test1" }
curl
curl -i -X POST http://localhost:8812/uc-api/load_driver -H 'Content-Type: application/json' --data-raw '{"i": "my", "k": "mykey", "m": "multistep", "p": "test1"}'
wget
wget -S -O- http://localhost:8812/uc-api/load_driver --header='Content-Type: application/json' --post-data='{"i": "my", "k": "mykey", "m": "multistep", "p": "test1"}'
httpie
echo '{
"i": "my",
"k": "mykey",
"m": "multistep",
"p": "test1"
}' | http POST http://localhost:8812/uc-api/load_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/load_driver', headers={
'Content-Type': 'application/json',
}, json={
'i': 'my',
'k': 'mykey',
'm': 'multistep',
'p': 'test1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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": "test1.my",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"lpi_id": "my",
"mod": "multistep",
"oid": "driver:uc/mws1-v1/test1.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": "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"
},
"phi_id": "test1",
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- i LPI ID
- m LPI module
- p PHI ID
Optionally:
- c Driver (LPI) configuration, optional
- save save configuration after successful call
modhelp_lpi - get LPI usage help
http
POST /uc-api/modhelp_lpi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "multistep", "c": "cfg" }
curl
curl -i -X POST http://localhost:8812/uc-api/modhelp_lpi -H 'Content-Type: application/json' --data-raw '{"c": "cfg", "k": "mykey", "m": "multistep"}'
wget
wget -S -O- http://localhost:8812/uc-api/modhelp_lpi --header='Content-Type: application/json' --post-data='{"c": "cfg", "k": "mykey", "m": "multistep"}'
httpie
echo '{
"c": "cfg",
"k": "mykey",
"m": "multistep"
}' | http POST http://localhost:8812/uc-api/modhelp_lpi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modhelp_lpi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'cfg',
'k': 'mykey',
'm': 'multistep',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- m LPI module name (without .py extension)
- c help context (cfg, action or update)
modinfo_lpi - get LPI module info
http
POST /uc-api/modinfo_lpi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "multistep" }
curl
curl -i -X POST http://localhost:8812/uc-api/modinfo_lpi -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "multistep"}'
wget
wget -S -O- http://localhost:8812/uc-api/modinfo_lpi --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "multistep"}'
httpie
echo '{
"k": "mykey",
"m": "multistep"
}' | http POST http://localhost:8812/uc-api/modinfo_lpi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modinfo_lpi', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'multistep',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with master permissions
- m LPI module name (without .py extension)
set_driver_prop - set driver (LPI) configuration property
appends property to LPI configuration and reloads module
http
POST /uc-api/set_driver_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1.my", "p": "bose", "v": 1, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/set_driver_prop -H 'Content-Type: application/json' --data-raw '{"i": "test1.my", "k": "mykey", "p": "bose", "save": true, "v": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/set_driver_prop --header='Content-Type: application/json' --post-data='{"i": "test1.my", "k": "mykey", "p": "bose", "save": true, "v": 1}'
httpie
echo '{
"i": "test1.my",
"k": "mykey",
"p": "bose",
"save": true,
"v": 1
}' | http POST http://localhost:8812/uc-api/set_driver_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/set_driver_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1.my',
'k': 'mykey',
'p': 'bose',
'save': True,
'v': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i driver ID
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save driver configuration after successful call
unload_driver - unload driver
Unloads driver. Driver should not be used by any item.
http
POST /uc-api/unload_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1.my" }
curl
curl -i -X POST http://localhost:8812/uc-api/unload_driver -H 'Content-Type: application/json' --data-raw '{"i": "test1.my", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/unload_driver --header='Content-Type: application/json' --post-data='{"i": "test1.my", "k": "mykey"}'
httpie
echo '{
"i": "test1.my",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/unload_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/unload_driver', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1.my',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i driver ID
Devices
deploy_device - deploy device items from template
Deploys the device from the specified template.
http
POST /uc-api/deploy_device HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "device1", "c": "PORT=2,ID=5", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/deploy_device -H 'Content-Type: application/json' --data-raw '{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
wget
wget -S -O- http://localhost:8812/uc-api/deploy_device --header='Content-Type: application/json' --post-data='{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
httpie
echo '{
"c": "PORT=2,ID=5",
"k": "mykey",
"save": true,
"t": "device1"
}' | http POST http://localhost:8812/uc-api/deploy_device Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/deploy_device', headers={
'Content-Type': 'application/json',
}, json={
'c': 'PORT=2,ID=5',
'k': 'mykey',
'save': True,
't': 'device1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
list_device_tpl - list device templates
List available device templates from runtime/tpl
http
POST /uc-api/list_device_tpl HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_device_tpl -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_device_tpl --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_device_tpl Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_device_tpl', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
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:
- k API key with masterkey permissions
undeploy_device - delete device items
Works in an opposite way to deploy_device - deploy device items from template function, destroying all items specified in the template.
http
POST /uc-api/undeploy_device HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "device1", "c": "PORT=2,ID=5" }
curl
curl -i -X POST http://localhost:8812/uc-api/undeploy_device -H 'Content-Type: application/json' --data-raw '{"c": "PORT=2,ID=5", "k": "mykey", "t": "device1"}'
wget
wget -S -O- http://localhost:8812/uc-api/undeploy_device --header='Content-Type: application/json' --post-data='{"c": "PORT=2,ID=5", "k": "mykey", "t": "device1"}'
httpie
echo '{
"c": "PORT=2,ID=5",
"k": "mykey",
"t": "device1"
}' | http POST http://localhost:8812/uc-api/undeploy_device Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/undeploy_device', headers={
'Content-Type': 'application/json',
}, json={
'c': 'PORT=2,ID=5',
'k': 'mykey',
't': 'device1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k 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.
update_device - update device items
Works similarly to deploy_device - deploy device items from template function but doesn’t create new items, updating the item configuration of the existing ones.
http
POST /uc-api/update_device HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "device1", "c": "PORT=2,ID=5", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/update_device -H 'Content-Type: application/json' --data-raw '{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
wget
wget -S -O- http://localhost:8812/uc-api/update_device --header='Content-Type: application/json' --post-data='{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
httpie
echo '{
"c": "PORT=2,ID=5",
"k": "mykey",
"save": true,
"t": "device1"
}' | http POST http://localhost:8812/uc-api/update_device Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/update_device', headers={
'Content-Type': 'application/json',
}, json={
'c': 'PORT=2,ID=5',
'k': 'mykey',
'save': True,
't': 'device1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k 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