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 see UC RESTful API.

API basics

JSON RPC

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

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

Note

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

JSON RPC API URL:

http://<ip_address:8812>/jrpc

or

http://<ip_address:8812>

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

JSON RPC payload encoding

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

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

JSON RPC error responses

JSON RPC calls return the following error codes:

  • 1 the item or resource is not found

  • 2 access is denied with the set API key

  • 6 Attempt to call undefined API method/function

  • 10 API function failed (all errors not listed here fall within this category)

  • 11 API function is called with invalid params

  • 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed

  • 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment

  • 14 the method is not implemented in/for requested resource

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

Warning

It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.

JSON RPC via HTTP GET

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

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

http://<ip_address:8812>/jrpc?i=ID&m=METHOD&p=PARAMS

where:

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

  • METHOD JSON RPC method to call

  • PARAMS method params, as url-encoded JSON

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

http://<ip_address:8812>/jrpc?i=1&m=test&p=%7B%22k%22%3A%22mykey%22%7D

Note

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

Direct API

Warning

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

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.

Direct API responses

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

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

Standard responses in status/body:

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

Standard error responses in status:

  • 400 Bad Request Invalid request params

  • 403 Forbidden the API key has no access to this function or resource

  • 404 Not Found method or resource/object doesn’t exist

  • 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST

  • 409 Conflict resource/object already exists or is locked

  • 500 API Error API function execution has been failed. Check input parameters and server logs.

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

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

Contents

Item functions

action - unit control action

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • i unit id

Optionally:

  • s desired unit status

  • v desired unit value

  • w wait for the completion for the specified number of seconds

  • u action UUID (will be auto generated if none specified)

  • p queue priority (default is 100, lower is better)

  • q global queue timeout, if expires, action is marked as “dead”

Returns:

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

action_toggle - toggle unit status

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • i unit id

Optionally:

  • w wait for the completion for the specified number of seconds

  • u action UUID (will be auto generated if none specified)

  • p queue priority (default is 100, lower is better)

  • q global queue timeout, if expires, action is marked as “dead”

Returns:

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

disable_actions - disable unit actions

Disables unit to run and queue new actions.

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • i unit id

enable_actions - enable unit actions

Enables unit to run and queue new actions.

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • i unit id

groups - get item group list

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • i unit id

Returns:

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

q_clean - clean action queue of unit

Cancels all queued actions, keeps the current action running.

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • i unit id

result - get action status

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

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 105
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

Optionally:

  • u action uuid or

  • i unit 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 158
Host: localhost:8812

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

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "start_item_maintenance",
  "params": {
    "i": "sensor:tests/sensor1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:158 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 127
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

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

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • a history notifier id (default: db_1)

  • i item oids or full ids, list or comma separated

Optionally:

  • s start time (timestamp or ISO or e.g. 1D for -1 day)

  • e end time (timestamp or ISO or e.g. 1D for -1 day)

  • l records limit (doesn’t work with “w”)

  • x state prop (“status” or “value”)

  • t time format (“iso” or “raw” for unix timestamp, default is “raw”)

  • z Time zone (pytz, e.g. UTC or Europe/Prague)

  • w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified

  • g output format (“list”, “dict” or “chart”, default is “list”)

  • c options for chart (dict or comma separated)

  • o extra options for notifier data request

Returns:

history data in specified format or chart image.

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

Options for chart (all are optional):

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

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

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

state_log - get item state log

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

note: only SQL notifiers are supported

Difference from state_history method:

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

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

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

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

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295099.9760036,
            "value": null
        },
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295103.9991317,
            "value": 25.0
        },
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295107.0097003,
            "value": 258.0
        },
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295110.0616019,
            "value": 359.0
        },
        {
            "oid": "sensor:tests/test1",
            "status": 1,
            "t": 1607295713.5383759,
            "value": 772.0
        }
    ]
}

Parameters:

  • k valid API key

  • a history notifier id (default: db_1)

  • i item oid or oid mask (type:group/subgroup/#)

Optionally:

  • s start time (timestamp or ISO or e.g. 1D for -1 day)

  • e end time (timestamp or ISO or e.g. 1D for -1 day)

  • l records limit (doesn’t work with “w”)

  • t time format (“iso” or “raw” for unix timestamp, default is “raw”)

  • z Time zone (pytz, e.g. UTC or Europe/Prague)

  • o extra options for notifier data request

Returns:

state log records (list)

stop_item_maintenance - stop item maintenance mode

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 157
Host: localhost:8812

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

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "stop_item_maintenance",
  "params": {
    "i": "sensor:tests/sensor1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:157 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k masterkey

  • i item ID

terminate - terminate action execution

Terminates or cancel the action if it is still queued

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k valid API key

  • u action uuid or

  • i unit id

Returns:

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

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 179
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "update",
    "params": {
        "i": "sensor:tests/sensor1",
        "k": "mykey",
        "s": 1,
        "v": 29.445
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 179" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "update", "params": {"i": "sensor:tests/sensor1", "k": "mykey", "s": 1, "v": 29.445}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 179" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "update", "params": {"i": "sensor:tests/sensor1", "k": "mykey", "s": 1, "v": 29.445}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "update",
  "params": {
    "i": "sensor:tests/sensor1",
    "k": "mykey",
    "s": 1,
    "v": 29.445
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:179 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '179', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'update', 'params': {'i': 'sensor:tests/sensor1', 'k': 'mykey', 's': 1, 'v': 29.445}})

response

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

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

Parameters:

  • k valid API key

  • i item id

Optionally:

  • s item status

  • v item value

Item management

list - list items

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 103
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "description": "",
            "full_id": "tests/mu1",
            "group": "tests",
            "id": "mu1",
            "oid": "mu:tests/mu1",
            "type": "mu"
        },
        {
            "description": "",
            "full_id": "clone_of_tests/sensor1",
            "group": "clone_of_tests",
            "id": "sensor1",
            "oid": "sensor:clone_of_tests/sensor1",
            "type": "sensor"
        },
        {
            "description": "",
            "full_id": "clone_of_tests/sensor5",
            "group": "clone_of_tests",
            "id": "sensor5",
            "oid": "sensor:clone_of_tests/sensor5",
            "type": "sensor"
        },
        {
            "description": "",
            "full_id": "clone_of_tests/t5",
            "group": "clone_of_tests",
            "id": "t5",
            "oid": "sensor:clone_of_tests/t5",
            "type": "sensor"
        },
        {
            "description": "",
            "full_id": "tests/sensor1",
            "group": "tests",
            "id": "sensor1",
            "oid": "sensor:tests/sensor1",
            "type": "sensor"
        },
        {
            "description": "",
            "full_id": "tests/sensor5",
            "group": "tests",
            "id": "sensor5",
            "oid": "sensor:tests/sensor5",
            "type": "sensor"
        },
        {
            "description": "",
            "full_id": "tests/t5",
            "group": "tests",
            "id": "t5",
            "oid": "sensor:tests/t5",
            "type": "sensor"
        },
        {
            "description": "",
            "full_id": "clone_of_tests/clone_of_unit1",
            "group": "clone_of_tests",
            "id": "clone_of_unit1",
            "oid": "unit:clone_of_tests/clone_of_unit1",
            "type": "unit"
        },
        {
            "description": "",
            "full_id": "clone_of_tests/unit1",
            "group": "clone_of_tests",
            "id": "unit1",
            "oid": "unit:clone_of_tests/unit1",
            "type": "unit"
        },
        {
            "description": "",
            "full_id": "tests/clone_of_unit1",
            "group": "tests",
            "id": "clone_of_unit1",
            "oid": "unit:tests/clone_of_unit1",
            "type": "unit"
        },
        {
            "description": "",
            "full_id": "tests/unit1",
            "group": "tests",
            "id": "unit1",
            "oid": "unit:tests/unit1",
            "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 166
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create",
    "params": {
        "i": "sensor:tests/sensor1",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 166" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create", "params": {"i": "sensor:tests/sensor1", "k": "mykey", "save": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 166" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create", "params": {"i": "sensor:tests/sensor1", "k": "mykey", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create",
  "params": {
    "i": "sensor:tests/sensor1",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:166 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '166', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create', 'params': {'i': 'sensor:tests/sensor1', 'k': 'mykey', 'save': 'true'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "full_id": "tests/sensor1",
        "group": "tests",
        "id": "sensor1",
        "oid": "sensor:tests/sensor1",
        "status": 0,
        "type": "sensor",
        "value": ""
    }
}

Parameters:

  • k API key with master permissions

  • i item oid (type:group/id)

Optionally:

  • g item group

  • e enabled actions/updates

  • save save multi-update configuration immediately

create_mu - create multi-update

Creates new multi-update.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 161
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_mu",
    "params": {
        "i": "mu:tests/mu1",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 161" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_mu", "params": {"i": "mu:tests/mu1", "k": "mykey", "save": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 161" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_mu", "params": {"i": "mu:tests/mu1", "k": "mykey", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_mu",
  "params": {
    "i": "mu:tests/mu1",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:161 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '161', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_mu', 'params': {'i': 'mu:tests/mu1', 'k': 'mykey', 'save': 'true'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "full_id": "tests/mu1",
        "group": "tests",
        "id": "mu1",
        "oid": "mu:tests/mu1",
        "status": 0,
        "type": "mu",
        "value": ""
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 166
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_sensor",
    "params": {
        "i": "tests/sensor5",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 166" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_sensor", "params": {"i": "tests/sensor5", "k": "mykey", "save": "true"}}'

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_sensor",
  "params": {
    "i": "tests/sensor5",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:166 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '166', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_sensor', 'params': {'i': 'tests/sensor5', 'k': 'mykey', 'save': 'true'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "full_id": "tests/sensor5",
        "group": "tests",
        "id": "sensor5",
        "oid": "sensor:tests/sensor5",
        "status": 0,
        "type": "sensor",
        "value": ""
    }
}

Parameters:

  • k API key with master permissions

  • i sensor id

Optionally:

  • g sensor group

  • e enabled updates

  • save save sensor configuration immediately

create_unit - create new unit

Creates new unit.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 162
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_unit",
    "params": {
        "i": "tests/unit1",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 162" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_unit", "params": {"i": "tests/unit1", "k": "mykey", "save": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 162" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_unit", "params": {"i": "tests/unit1", "k": "mykey", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_unit",
  "params": {
    "i": "tests/unit1",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:162 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '162', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_unit', 'params': {'i': 'tests/unit1', 'k': 'mykey', 'save': 'true'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "action_enabled": false,
        "full_id": "tests/unit1",
        "group": "tests",
        "id": "unit1",
        "nstatus": 0,
        "nvalue": "",
        "oid": "unit:tests/unit1",
        "status": 0,
        "type": "unit",
        "value": ""
    }
}

Parameters:

  • k API key with master permissions

  • i unit id

Optionally:

  • g unit group

  • e enabled actions

  • 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 139
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i item id

  • g group (either item or group must be specified)

get_config - get item configuration

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "action_enabled": true,
        "full_id": "tests/unit1",
        "group": "tests",
        "id": "unit1",
        "maintenance_duration": 0,
        "notify_events": 2,
        "oid": "unit:tests/unit1",
        "type": "unit",
        "value_in_range_max": null,
        "value_in_range_max_eq": false,
        "value_in_range_min": null,
        "value_in_range_min_eq": false
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 142
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "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,
        "maintenance_duration": 0,
        "modbus_status": null,
        "modbus_value": null,
        "mqtt_control": null,
        "mqtt_update": null,
        "notify_events": 2,
        "snmp_trap": null,
        "status_labels": {
            "0": "OFF",
            "1": "ON"
        },
        "term_kill_interval": null,
        "update_driver_config": null,
        "update_exec": null,
        "update_exec_after_action": false,
        "update_if_action": false,
        "update_interval": 0,
        "update_state_after_action": true,
        "update_timeout": null,
        "value_condition": "",
        "value_in_range_max": null,
        "value_in_range_max_eq": false,
        "value_in_range_min": null,
        "value_in_range_min_eq": 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 143
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i item id

set_prop - set item property

Set configuration parameters of the item.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 202
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_prop",
    "params": {
        "i": "unit:tests/unit1",
        "k": "mykey",
        "p": "action_allow_termination",
        "v": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 202" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_prop", "params": {"i": "unit:tests/unit1", "k": "mykey", "p": "action_allow_termination", "v": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 202" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_prop", "params": {"i": "unit:tests/unit1", "k": "mykey", "p": "action_allow_termination", "v": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_prop",
  "params": {
    "i": "unit:tests/unit1",
    "k": "mykey",
    "p": "action_allow_termination",
    "v": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:202 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '202', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_prop', 'params': {'i': 'unit:tests/unit1', 'k': 'mykey', 'p': 'action_allow_termination', 'v': 'true'}})

response

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

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 179
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "action_enabled": true,
        "full_id": "tests/clone_of_unit1",
        "group": "tests",
        "id": "clone_of_unit1",
        "nstatus": 0,
        "nvalue": "",
        "oid": "unit:tests/clone_of_unit1",
        "status": 0,
        "type": "unit",
        "value": ""
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 163
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "clone_group",
    "params": {
        "g": "tests",
        "k": "mykey",
        "n": "clone_of_tests"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 163" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "clone_group", "params": {"g": "tests", "k": "mykey", "n": "clone_of_tests"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 163" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "clone_group", "params": {"g": "tests", "k": "mykey", "n": "clone_of_tests"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "clone_group",
  "params": {
    "g": "tests",
    "k": "mykey",
    "n": "clone_of_tests"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:163 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '163', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'clone_group', 'params': {'g': 'tests', 'k': 'mykey', 'n': 'clone_of_tests'}})

response

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

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

Parameters:

  • k API key with master permissions

  • 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 266
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_owfs_bus",
    "params": {
        "d": 0.3,
        "i": "bus_local",
        "k": "mykey",
        "l": "true",
        "n": "localhost:4304",
        "r": 5,
        "save": "true",
        "t": 1
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 266" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_owfs_bus", "params": {"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/jrpc --header="Accept: application/json" --header="Content-Length: 266" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_owfs_bus", "params": {"d": 0.3, "i": "bus_local", "k": "mykey", "l": "true", "n": "localhost:4304", "r": 5, "save": "true", "t": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_owfs_bus",
  "params": {
    "d": 0.3,
    "i": "bus_local",
    "k": "mykey",
    "l": "true",
    "n": "localhost:4304",
    "r": 5,
    "save": "true",
    "t": 1
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:266 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '266', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_owfs_bus', 'params': {'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
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 141
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "destroy_owfs_bus",
    "params": {
        "i": "bus_local",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "destroy_owfs_bus",
  "params": {
    "i": "bus_local",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:141 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i bus ID

get_owfs_bus - get OWFS bus configuration

http

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_owfs_bus",
    "params": {
        "i": "bus_local",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 114
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "delay": 0.3,
            "id": "bus_local",
            "location": "localhost:4304",
            "lock": true,
            "retries": 5,
            "timeout": 1.0
        }
    ]
}

Parameters:

  • k API key with master permissions

scan_owfs_bus - scan OWFS bus

Scan OWFS bus for connected 1-Wire devices.

http

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "scan_owfs_bus",
    "params": {
        "i": "bus_local",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "scan_owfs_bus",
  "params": {
    "i": "bus_local",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:138 Content-Type:application/json

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "path": "10.67C6697351FF",
            "type": "DS18S20"
        },
        {
            "path": "05.4AEC29CDBAAB",
            "type": "DS2405"
        }
    ]
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 138
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "test_owfs_bus",
    "params": {
        "i": "bus_local",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "test_owfs_bus",
  "params": {
    "i": "bus_local",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:138 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 273
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_modbus_port",
    "params": {
        "d": 0.2,
        "i": "mbp1",
        "k": "mykey",
        "l": "true",
        "p": "udp:192.168.33.33:502",
        "r": 3,
        "save": "true",
        "t": 0.5
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 273" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_modbus_port", "params": {"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/jrpc --header="Accept: application/json" --header="Content-Length: 273" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_modbus_port", "params": {"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 '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_modbus_port",
  "params": {
    "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/jrpc Accept:application/json Content-Length:273 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '273', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_modbus_port', 'params': {'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
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 139
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "destroy_modbus_port",
    "params": {
        "i": "mbp1",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "destroy_modbus_port",
  "params": {
    "i": "mbp1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:139 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i virtual port ID

get_modbus_port - get virtual Modbus port configuration

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 135
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_modbus_port",
    "params": {
        "i": "mbp1",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_modbus_port",
  "params": {
    "i": "mbp1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:135 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '135', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_modbus_port', 'params': {'i': 'mbp1', 'k': 'mykey'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 116
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "delay": 0.02,
            "id": "local",
            "lock": false,
            "params": "tcp:localhost:5502",
            "retries": 0,
            "timeout": 4.0
        },
        {
            "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 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

Float32 numbers are returned as Python-converted floats and may have broken precision. Consider converting back to f32 on the client side.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 181
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "read_modbus_port",
    "params": {
        "i": "h10-12,c5-6",
        "k": "mykey",
        "p": "local",
        "s": 1
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 181" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "read_modbus_port", "params": {"i": "h10-12,c5-6", "k": "mykey", "p": "local", "s": 1}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 181" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "read_modbus_port", "params": {"i": "h10-12,c5-6", "k": "mykey", "p": "local", "s": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "read_modbus_port",
  "params": {
    "i": "h10-12,c5-6",
    "k": "mykey",
    "p": "local",
    "s": 1
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:181 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '181', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'read_modbus_port', 'params': {'i': 'h10-12,c5-6', 'k': 'mykey', 'p': 'local', 's': 1}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "addr": "c5",
            "type": "coil",
            "value": 0
        },
        {
            "addr": "c6",
            "type": "coil",
            "value": 0
        },
        {
            "addr": "h10",
            "type": "u16",
            "value": 0
        },
        {
            "addr": "h11",
            "type": "u16",
            "value": 0
        },
        {
            "addr": "h12",
            "type": "u16",
            "value": 0
        }
    ]
}

Parameters:

  • k API key with master permissions

  • p Modbus virtual port

  • s Slave ID

  • i Modbus register(s)

  • f data type (u16, i16, u32, i32, u64, i64, f32 or bit)

  • c count, if register range not specified

Optionally:

  • t max allowed timeout for the operation

test_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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "test_modbus_port",
    "params": {
        "i": "mbp1",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i 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).

To set bit, specify register as hX/Y where X = register number, Y = bit number (supports u16, u32, u64 data types)

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 193
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "write_modbus_port",
    "params": {
        "i": "h10",
        "k": "mykey",
        "p": "local",
        "s": 1,
        "v": 2522
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 193" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "write_modbus_port", "params": {"i": "h10", "k": "mykey", "p": "local", "s": 1, "v": 2522}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 193" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "write_modbus_port", "params": {"i": "h10", "k": "mykey", "p": "local", "s": 1, "v": 2522}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "write_modbus_port",
  "params": {
    "i": "h10",
    "k": "mykey",
    "p": "local",
    "s": 1,
    "v": 2522
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:193 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '193', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'write_modbus_port', 'params': {'i': 'h10', 'k': 'mykey', 'p': 'local', 's': 1, 'v': 2522}})

response

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

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

Parameters:

  • k API key with master permissions

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

  • f data type (u16, i16, u32, i32, u64, i64, f32), ignored if z=True

Optionally:

  • t max allowed timeout for the operation

get_modbus_slave_data - get 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 154
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_modbus_slave_data",
    "params": {
        "i": "h1000-1005,c10-15",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 154" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_modbus_slave_data", "params": {"i": "h1000-1005,c10-15", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 154" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_modbus_slave_data", "params": {"i": "h1000-1005,c10-15", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_modbus_slave_data",
  "params": {
    "i": "h1000-1005,c10-15",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:154 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '154', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_modbus_slave_data', 'params': {'i': 'h1000-1005,c10-15', 'k': 'mykey'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "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)

  • f data type (u16, i16, u32, i32, u64, i64, f32 or bit)

  • c count, if register range not specified

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 198
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "exec_phi",
    "params": {
        "a": "/opt/firmware/fw.dat",
        "c": "update_firmware",
        "i": "test1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 198" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "exec_phi", "params": {"a": "/opt/firmware/fw.dat", "c": "update_firmware", "i": "test1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 198" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "exec_phi", "params": {"a": "/opt/firmware/fw.dat", "c": "update_firmware", "i": "test1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "exec_phi",
  "params": {
    "a": "/opt/firmware/fw.dat",
    "c": "update_firmware",
    "i": "test1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:198 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '198', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'exec_phi', 'params': {'a': '/opt/firmware/fw.dat', 'c': 'update_firmware', 'i': 'test1', 'k': 'mykey'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "output": "not implemented"
    }
}

Parameters:

  • k API key with master permissions

  • i PHI id

  • c command to exec

  • a command argument

get_phi - get loaded PHI information

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 128
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_phi",
    "params": {
        "i": "test1",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api": 9,
        "author": "Altertech Group, https://www.altertech.com/",
        "can_discover": null,
        "can_get_ports": true,
        "cfg": {
            "default_status": 0
        },
        "description": "Emulates 16-port relay",
        "equipment": [
            "virtual"
        ],
        "features": [
            "aao_get",
            "aao_set",
            "push",
            "action",
            "port_get",
            "port_set"
        ],
        "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/lab-ws2/test1",
        "required": [
            "action",
            "port_get",
            "port_set"
        ],
        "version": "1.4.0"
    }
}

Parameters:

  • k API key with master permissions

  • i PHI ID

get_phi_ports - get list of PHI ports

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 134
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_phi_ports",
    "params": {
        "i": "test1",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 107
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "id": "test1",
            "mod": "vrtrelay"
        }
    ]
}

Parameters:

  • k API key with master permissions

  • full get exntended information

list_phi_mods - get list of available PHI modules

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 112
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "api": 9,
            "author": "Altertech, https://www.altertech.com/",
            "can_discover": null,
            "can_get_ports": true,
            "description": "Ethernet/IP sensors generic",
            "equipment": [
                "Ethernet/IP"
            ],
            "features": [
                "aao_get",
                "port_get",
                "value"
            ],
            "help": "\nEthernet/IP sensors driver\n\nTag list file: text file with one tag per line\n\nIf timeout it specified, it MUST be small enough, otherwise PHI will\nnot even try to connect to En/IP equipment (default is core timeout - 2 sec).\n",
            "id": null,
            "license": "GNU GPL v3",
            "lpi_default": "sensor",
            "mod": "enip_sensor",
            "mods_required": [
                ""
            ],
            "oid": null,
            "required": [
                "port_get",
                "value"
            ],
            "version": "1.0.3"
        },
        {
            "api": 9,
            "author": "Altertech, https://www.altertech.com/",
            "can_discover": null,
            "can_get_ports": true,
            "description": "Ethernet/IP units generic",
            "equipment": [
                "Ethernet/IP"
            ],
            "features": [
                "aao_get",
                "aao_set",
                "action",
                "port_get",
                "port_set"
            ],
            "help": "\nEthernet/IP units driver\n\nTag list file: text file with one tag per line\n\nIn case of problems, it's highly recommended to specify tag variable type, as\nTAG:TYPE. Valid types are:\n\nREAL, SINT, USINT, INT, UINT, DINT, UDINT, BOOL, WORD, DWORD, IPADDR, STRING,\nSSTRING\n\nIf timeout it specified, it MUST be small enough, otherwise PHI will\nnot even try to connect to En/IP equipment (default is core timeout - 2 sec).\n",
            "id": null,
            "license": "GNU GPL v3",
            "lpi_default": "basic",
            "mod": "enip_xvunit",
            "mods_required": [
                ""
            ],
            "oid": null,
            "required": [
                "action",
                "port_get",
                "port_set"
            ],
            "version": "1.0.3"
        },
        {
            "api": 5,
            "author": "Altertech Group, https://www.altertech.com/",
            "can_discover": [
                "net"
            ],
            "can_get_ports": false,
            "description": "Nanoleaf LEDs",
            "equipment": [
                "Nanoleaf LEDs"
            ],
            "features": [
                "action",
                "port_get",
                "port_set",
                "status",
                "value"
            ],
            "help": "\nNanoleaf (https://nanoleaf.me/) LEDs control.\n\nIf token is not specified, Nanoleaf power button must be pressed for 7 seconds\nbefore loading PHI.\n\nIf unit value is specified as RGB hex, PHI sets its color, otherwise chosen\neffect is applied.\n",
            "id": null,
            "license": "Apache License 2.0",
            "lpi_default": "usp",
            "mod": "nanoleaf",
            "mods_required": [],
            "oid": null,
            "required": [
                "action",
                "port_get",
                "port_set",
                "status",
                "value"
            ],
            "version": "1.0.3"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "can_discover": null,
            "can_get_ports": true,
            "description": "Emulates 16-port relay",
            "equipment": [
                "virtual"
            ],
            "features": [
                "aao_get",
                "aao_set",
                "push",
                "action",
                "port_get",
                "port_set"
            ],
            "help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
            "id": null,
            "license": "Apache License 2.0",
            "lpi_default": "basic",
            "mod": "vrtrelay",
            "mods_required": [],
            "oid": null,
            "required": [
                "action",
                "port_get",
                "port_set"
            ],
            "version": "1.4.0"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "can_discover": null,
            "can_get_ports": true,
            "description": "Emulates virtual sensors",
            "equipment": [
                "virtual"
            ],
            "features": [
                "aao_get",
                "push",
                "port_get",
                "value"
            ],
            "help": "\nSimple virtual sensor controller, may be used for the various tests/debugging.\nWhen loaded, simulates sensors with ports 1000..1010, which may be extended,\nalso any labels for the sensors (including strings) may be used. Virtual\nsensors can be set to float values only.\n",
            "id": null,
            "license": "Apache License 2.0",
            "lpi_default": "sensor",
            "mod": "vrtsensors",
            "mods_required": [],
            "oid": null,
            "required": [
                "port_get",
                "value"
            ],
            "version": "1.3.0"
        }
    ]
}

Parameters:

  • k API key with master permissions

load_phi - load PHI module

Loads Physical Interface.

http

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "load_phi",
    "params": {
        "c": "default_status=0",
        "i": "test1",
        "k": "mykey",
        "m": "vrtrelay",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 211" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "load_phi", "params": {"c": "default_status=0", "i": "test1", "k": "mykey", "m": "vrtrelay", "save": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 211" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "load_phi", "params": {"c": "default_status=0", "i": "test1", "k": "mykey", "m": "vrtrelay", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "load_phi",
  "params": {
    "c": "default_status=0",
    "i": "test1",
    "k": "mykey",
    "m": "vrtrelay",
    "save": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:211 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '211', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'load_phi', 'params': {'c': 'default_status=0', 'i': 'test1', 'k': 'mykey', 'm': 'vrtrelay', 'save': 'true'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api": 9,
        "author": "Altertech Group, https://www.altertech.com/",
        "can_discover": null,
        "can_get_ports": true,
        "cfg": {
            "default_status": 0
        },
        "description": "Emulates 16-port relay",
        "equipment": [
            "virtual"
        ],
        "features": [
            "aao_get",
            "aao_set",
            "push",
            "action",
            "port_get",
            "port_set"
        ],
        "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/lab-ws2/test1",
        "required": [
            "action",
            "port_get",
            "port_set"
        ],
        "version": "1.4.0"
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 155
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "modhelp_phi",
    "params": {
        "c": "cfg",
        "k": "mykey",
        "m": "vrtrelay"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 155" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "modhelp_phi", "params": {"c": "cfg", "k": "mykey", "m": "vrtrelay"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 155" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "modhelp_phi", "params": {"c": "cfg", "k": "mykey", "m": "vrtrelay"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "modhelp_phi",
  "params": {
    "c": "cfg",
    "k": "mykey",
    "m": "vrtrelay"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:155 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '155', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'modhelp_phi', 'params': {'c': 'cfg', 'k': 'mykey', 'm': 'vrtrelay'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "help": "ports status on load (default: 0)",
            "name": "default_status",
            "required": false,
            "type": "int"
        },
        {
            "help": "full state (status/value)",
            "name": "state_full",
            "required": false,
            "type": "bool"
        },
        {
            "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 135
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "modinfo_phi",
    "params": {
        "k": "mykey",
        "m": "vrtrelay"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "modinfo_phi",
  "params": {
    "k": "mykey",
    "m": "vrtrelay"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:135 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '135', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'modinfo_phi', 'params': {'k': 'mykey', 'm': 'vrtrelay'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api": 9,
        "author": "Altertech Group, https://www.altertech.com/",
        "can_discover": null,
        "can_get_ports": true,
        "description": "Emulates 16-port relay",
        "equipment": [
            "virtual"
        ],
        "features": [
            "aao_get",
            "aao_set",
            "push",
            "action",
            "port_get",
            "port_set"
        ],
        "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": [
            "action",
            "port_get",
            "port_set"
        ],
        "version": "1.4.0"
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "phi_discover",
    "params": {
        "k": "mykey",
        "m": "nanoleaf"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "phi_discover",
  "params": {
    "k": "mykey",
    "m": "nanoleaf"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'phi_discover', 'params': {'k': 'mykey', 'm': 'nanoleaf'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "!opt": "cols",
            "value": [
                "IP",
                "Name"
            ]
        },
        {
            "!load": {
                "host": "10.90.1.81"
            },
            "IP": "10.90.1.81",
            "Name": "Nanoleaf Light Panels 54:e7:31"
        }
    ]
}

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

push_phi_state - push state to PHI module

Allows to perform update of PHI ports by external application.

If called as RESTful, the whole request body is used as a payload (except fields “k”, “save”, “kind” and “method”, which are reserved)

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 156
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "push_phi_state",
    "params": {
        "i": "test1",
        "k": "mykey",
        "p": "test"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 156" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "push_phi_state", "params": {"i": "test1", "k": "mykey", "p": "test"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 156" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "push_phi_state", "params": {"i": "test1", "k": "mykey", "p": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "push_phi_state",
  "params": {
    "i": "test1",
    "k": "mykey",
    "p": "test"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:156 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '156', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'push_phi_state', 'params': {'i': 'test1', 'k': 'mykey', 'p': 'test'}})

response

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

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

Parameters:

  • k masterkey or a key with the write permission on “phi” group

  • i PHI id

  • p state payload, sent to PHI as-is

put_phi_mod - upload PHI module

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

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 171
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "put_phi_mod",
    "params": {
        "c": "<MODULE_CONTENT>",
        "k": "mykey",
        "m": "gpio_button"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 171" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "put_phi_mod", "params": {"c": "<MODULE_CONTENT>", "k": "mykey", "m": "gpio_button"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 171" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "put_phi_mod", "params": {"c": "<MODULE_CONTENT>", "k": "mykey", "m": "gpio_button"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "put_phi_mod",
  "params": {
    "c": "<MODULE_CONTENT>",
    "k": "mykey",
    "m": "gpio_button"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:171 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '171', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'put_phi_mod', 'params': {'c': '<MODULE_CONTENT>', 'k': 'mykey', 'm': 'gpio_button'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
        "result": {
            "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 204
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_phi_prop",
    "params": {
        "i": "test1",
        "k": "mykey",
        "p": "default_status",
        "save": "true",
        "v": 1
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 204" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_phi_prop", "params": {"i": "test1", "k": "mykey", "p": "default_status", "save": "true", "v": 1}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 204" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_phi_prop", "params": {"i": "test1", "k": "mykey", "p": "default_status", "save": "true", "v": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_phi_prop",
  "params": {
    "i": "test1",
    "k": "mykey",
    "p": "default_status",
    "save": "true",
    "v": 1
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:204 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '204', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_phi_prop', 'params': {'i': 'test1', 'k': 'mykey', 'p': 'default_status', 'save': 'true', 'v': 1}})

response

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

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 150
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "test_phi",
    "params": {
        "c": "self",
        "i": "test1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 150" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "test_phi", "params": {"c": "self", "i": "test1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 150" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "test_phi", "params": {"c": "self", "i": "test1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "test_phi",
  "params": {
    "c": "self",
    "i": "test1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:150 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '150', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'test_phi', 'params': {'c': 'self', 'i': 'test1', 'k': 'mykey'}})

response

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

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

Parameters:

  • k API key with master permissions

  • i PHI id

  • c test command

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 131
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "unload_phi",
    "params": {
        "i": "test1",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 213
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "assign_driver",
    "params": {
        "c": "port=5,dport=6,steps=1|1|2",
        "d": "test1.my",
        "i": "unit:tests/unit1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 213" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "assign_driver", "params": {"c": "port=5,dport=6,steps=1|1|2", "d": "test1.my", "i": "unit:tests/unit1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 213" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "assign_driver", "params": {"c": "port=5,dport=6,steps=1|1|2", "d": "test1.my", "i": "unit:tests/unit1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "assign_driver",
  "params": {
    "c": "port=5,dport=6,steps=1|1|2",
    "d": "test1.my",
    "i": "unit:tests/unit1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:213 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '213', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'assign_driver', 'params': {'c': 'port=5,dport=6,steps=1|1|2', 'd': 'test1.my', 'i': 'unit:tests/unit1', 'k': 'mykey'}})

response

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

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

Parameters:

  • k 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 134
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_driver",
    "params": {
        "i": "test1.my",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 134" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_driver", "params": {"i": "test1.my", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 134" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_driver", "params": {"i": "test1.my", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_driver",
  "params": {
    "i": "test1.my",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:134 Content-Type:application/json

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api": 9,
        "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\nFor reversible DC motor schema use \"port\" for plus (up) and \"dport\" for minus\n(down).\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/lab-ws2/test1.my",
        "phi": {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "can_discover": null,
            "can_get_ports": true,
            "cfg": {
                "default_status": 1
            },
            "description": "Emulates 16-port relay",
            "equipment": [
                "virtual"
            ],
            "features": [
                "aao_get",
                "aao_set",
                "push",
                "action",
                "port_get",
                "port_set"
            ],
            "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/lab-ws2/test1",
            "required": [
                "action",
                "port_get",
                "port_set"
            ],
            "version": "1.4.0"
        },
        "phi_id": "test1",
        "version": "1.2.1"
    }
}

Parameters:

  • k API key with master permissions

  • i PHI ID

list_drivers - list loaded drivers

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "features": [
                "status",
                "status_mp",
                "mu_status",
                "mu_status_mp",
                "port_get",
                "aao_get",
                "action",
                "action_mp",
                "port_set",
                "aao_set",
                "events",
                "value"
            ],
            "id": "test1.default",
            "lpi_id": "default",
            "mod": "basic",
            "phi_id": "test1"
        },
        {
            "features": [
                "action",
                "action_mp",
                "port_set",
                "aao_set"
            ],
            "id": "test1.my",
            "lpi_id": "my",
            "mod": "multistep",
            "phi_id": "test1"
        }
    ]
}

Parameters:

  • k API key with master permissions

  • full get exntended information

list_lpi_mods - get list of available LPI modules

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 112
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "api": 9,
            "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",
                "value"
            ],
            "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' e.g. 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, e.g. 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.3.0"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "connections": {
                "port": "primary"
            },
            "description": "test LPI mod",
            "features": [
                "status",
                "status_mp",
                "mu_status",
                "mu_status_mp",
                "port_get",
                "aao_get",
                "action",
                "action_mp",
                "port_set",
                "aao_set",
                "events",
                "value"
            ],
            "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' e.g. 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, e.g. 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": "btest",
            "oid": null,
            "phi_id": null,
            "version": "1.3.0"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "connections": {
                "port": "primary"
            },
            "description": "Enhanced sensor LPI",
            "features": [
                "value",
                "value_mp",
                "mu_value",
                "mu_value_mp",
                "port_get",
                "aao_get",
                "cfg",
                "events"
            ],
            "help": "\nEnhanced LPI to work with groups of sensors, supports various typical\nfunctions: working with a sensor groups, returning the average, max or min\ngroup value etc. Can use 'max_diff' param to control the maximum difference of\nthe sensor value in a group and automatically remove possible broken sensors\nfrom the result (if the number of good sensors in a group is more than broken).\n\nFor multiupdates all ports specified in mu should be lists.\n\nThis LPI is dedicated to work with a groups of sensors and doesn't support\nsingle sensor event processing.\n",
            "id": null,
            "license": "Apache License 2.0",
            "logic": "single and group polling",
            "lpi_id": null,
            "mod": "esensor",
            "oid": null,
            "phi_id": null,
            "version": "1.2.0"
        },
        {
            "api": 9,
            "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\nFor reversible DC motor schema use \"port\" for plus (up) and \"dport\" for minus\n(down).\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": null,
            "license": "Apache License 2.0",
            "logic": "multistep with delays",
            "lpi_id": null,
            "mod": "multistep",
            "oid": null,
            "phi_id": null,
            "version": "1.2.1"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "connections": {
                "port": "primary"
            },
            "description": "Basic sensor LPI",
            "features": [
                "value",
                "mu_value",
                "port_get",
                "aao_get",
                "cfg",
                "events"
            ],
            "help": "\nBasic LPI to work with sensors, doesn't process sensor value in any way,\nreturning it to controller as-is. ",
            "id": null,
            "license": "Apache License 2.0",
            "logic": "single polling",
            "lpi_id": null,
            "mod": "sensor",
            "oid": null,
            "phi_id": null,
            "version": "1.2.0"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "connections": {
                "port": "primary"
            },
            "description": "Single port sensor LPI",
            "features": [
                "value",
                "port_get",
                "events",
                "ssp"
            ],
            "help": "\nLPI to work with sensor PHIs which provide state for single sensor only\n(port=1), doesn't process sensor value in any way, returning it to controller\nas-is. ",
            "id": null,
            "license": "Apache License 2.0",
            "logic": "single port",
            "lpi_id": null,
            "mod": "ssp",
            "oid": null,
            "phi_id": null,
            "version": "1.2.0"
        },
        {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "connections": {
                "port": "primary"
            },
            "description": "Single port unit LPI",
            "features": [
                "status",
                "port_get",
                "port_set",
                "events",
                "usp",
                "value",
                "action"
            ],
            "help": "\nLPI to work with unit PHIs which provide/manage state for single unit only\n(port=1), doesn't process unit status in any way, returning it to controller\nas-is. For unit actions port is not required, however LPI sets it to 1 when\ntransmitting to PHIs.\n",
            "id": null,
            "license": "Apache License 2.0",
            "logic": "single port, basic status on/off",
            "lpi_id": null,
            "mod": "usp",
            "oid": null,
            "phi_id": null,
            "version": "1.3.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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 177
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "load_driver",
    "params": {
        "i": "my",
        "k": "mykey",
        "m": "multistep",
        "p": "test1"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 177" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "load_driver", "params": {"i": "my", "k": "mykey", "m": "multistep", "p": "test1"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 177" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "load_driver", "params": {"i": "my", "k": "mykey", "m": "multistep", "p": "test1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "load_driver",
  "params": {
    "i": "my",
    "k": "mykey",
    "m": "multistep",
    "p": "test1"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:177 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '177', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'load_driver', 'params': {'i': 'my', 'k': 'mykey', 'm': 'multistep', 'p': 'test1'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api": 9,
        "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\nFor reversible DC motor schema use \"port\" for plus (up) and \"dport\" for minus\n(down).\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/lab-ws2/test1.my",
        "phi": {
            "api": 9,
            "author": "Altertech Group, https://www.altertech.com/",
            "can_discover": null,
            "can_get_ports": true,
            "cfg": {
                "default_status": 0
            },
            "description": "Emulates 16-port relay",
            "equipment": [
                "virtual"
            ],
            "features": [
                "aao_get",
                "aao_set",
                "push",
                "action",
                "port_get",
                "port_set"
            ],
            "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/lab-ws2/test1",
            "required": [
                "action",
                "port_get",
                "port_set"
            ],
            "version": "1.4.0"
        },
        "phi_id": "test1",
        "version": "1.2.1"
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 156
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "modhelp_lpi",
    "params": {
        "c": "cfg",
        "k": "mykey",
        "m": "multistep"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 156" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "modhelp_lpi", "params": {"c": "cfg", "k": "mykey", "m": "multistep"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 156" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "modhelp_lpi", "params": {"c": "cfg", "k": "mykey", "m": "multistep"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "modhelp_lpi",
  "params": {
    "c": "cfg",
    "k": "mykey",
    "m": "multistep"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:156 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '156', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'modhelp_lpi', 'params': {'c': 'cfg', 'k': 'mykey', 'm': 'multistep'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "help": "allow action even if current status is error",
            "name": "bose",
            "required": false,
            "type": "bool"
        },
        {
            "help": "default: default circuit, rdc: reversible DC",
            "name": "logic",
            "required": false,
            "type": "enum:str:default,rdc"
        }
    ]
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "modinfo_lpi",
    "params": {
        "k": "mykey",
        "m": "multistep"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "modinfo_lpi",
  "params": {
    "k": "mykey",
    "m": "multistep"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'modinfo_lpi', 'params': {'k': 'mykey', 'm': 'multistep'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api": 9,
        "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\nFor reversible DC motor schema use \"port\" for plus (up) and \"dport\" for minus\n(down).\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.2.1"
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 200
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_driver_prop",
    "params": {
        "i": "test1.my",
        "k": "mykey",
        "p": "bose",
        "save": "true",
        "v": 1
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 200" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_driver_prop", "params": {"i": "test1.my", "k": "mykey", "p": "bose", "save": "true", "v": 1}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 200" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_driver_prop", "params": {"i": "test1.my", "k": "mykey", "p": "bose", "save": "true", "v": 1}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_driver_prop",
  "params": {
    "i": "test1.my",
    "k": "mykey",
    "p": "bose",
    "save": "true",
    "v": 1
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:200 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '200', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_driver_prop', 'params': {'i': 'test1.my', 'k': 'mykey', 'p': 'bose', 'save': 'true', 'v': 1}})

response

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

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

Parameters:

  • k API key with master permissions

  • i 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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 137
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "unload_driver",
    "params": {
        "i": "test1.my",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 137" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "unload_driver", "params": {"i": "test1.my", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 137" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "unload_driver", "params": {"i": "test1.my", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "unload_driver",
  "params": {
    "i": "test1.my",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:137 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i driver ID

Data pullers

create_datapuller - create data puller

Creates data puller with the specified configuration.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 186
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_datapuller",
    "params": {
        "c": "/opt/eva/xbin/dp1",
        "i": "test",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 186" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_datapuller", "params": {"c": "/opt/eva/xbin/dp1", "i": "test", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 186" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_datapuller", "params": {"c": "/opt/eva/xbin/dp1", "i": "test", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_datapuller",
  "params": {
    "c": "/opt/eva/xbin/dp1",
    "i": "test",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:186 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '186', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_datapuller', 'params': {'c': '/opt/eva/xbin/dp1', 'i': 'test', 'k': 'mykey'}})

response

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

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

Parameters:

  • k API key with master permissions

  • i data puller id

  • c data puller command

Optionally:

  • t data puller timeout (in seconds, default: default timeout)

  • e event timeout (default: none)

  • save save datapuller config after creation

Returns:

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

destroy_datapuller - destroy data puller

Creates data puller with the specified configuration.

http

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "destroy_datapuller",
    "params": {
        "i": "test",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "destroy_datapuller",
  "params": {
    "i": "test",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:138 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i data puller id

get_datapuller - Get data puller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 134
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_datapuller",
    "params": {
        "i": "test",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_datapuller",
  "params": {
    "i": "test",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:134 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '134', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_datapuller', 'params': {'i': 'test', 'k': 'mykey'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "active": true,
        "cmd": "/opt/test.sh -F /op/test.ini",
        "name": "test",
        "pid": 2398316
    }
}

Parameters:

  • k API key with master permissions

  • i data puller name

Returns:

Data puller info

list_datapullers - List data pullers

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "active": true,
            "cmd": "/opt/test.sh -F /op/test.ini",
            "name": "test",
            "pid": 2398316
        }
    ]
}

Parameters:

  • k API key with master permissions

Returns:

List of all configured data pullers

restart_datapuller - Restart data puller

http

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "restart_datapuller",
    "params": {
        "i": "test",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "restart_datapuller",
  "params": {
    "i": "test",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:138 Content-Type:application/json

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i data puller name

start_datapuller - Start data puller

http

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "start_datapuller",
    "params": {
        "i": "test",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • k API key with master permissions

  • i data puller name

stop_datapuller - Stop data puller

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 135
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "stop_datapuller",
    "params": {
        "i": "test",
        "k": "mykey"
    }
}

curl

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

wget

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

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "stop_datapuller",
  "params": {
    "i": "test",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:135 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '135', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'stop_datapuller', 'params': {'i': 'test', 'k': 'mykey'}})

response

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

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

Parameters:

  • k API key with master permissions

  • i data puller name

Devices

deploy_device - deploy device items from template

Deploys the device from the specified template.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 188
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "deploy_device",
    "params": {
        "c": "PORT=2,ID=5",
        "k": "mykey",
        "save": "true",
        "t": "device1"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 188" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "deploy_device", "params": {"c": "PORT=2,ID=5", "k": "mykey", "save": "true", "t": "device1"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 188" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "deploy_device", "params": {"c": "PORT=2,ID=5", "k": "mykey", "save": "true", "t": "device1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "deploy_device",
  "params": {
    "c": "PORT=2,ID=5",
    "k": "mykey",
    "save": "true",
    "t": "device1"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:188 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '188', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'deploy_device', 'params': {'c': 'PORT=2,ID=5', 'k': 'mykey', 'save': 'true', 't': 'device1'}})

response

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

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

Parameters:

  • k API key with allow=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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 114
Host: localhost:8812

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "name": "device1",
            "type": "YAML"
        }
    ]
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 166
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "undeploy_device",
    "params": {
        "c": "PORT=2,ID=5",
        "k": "mykey",
        "t": "device1"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 166" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "undeploy_device", "params": {"c": "PORT=2,ID=5", "k": "mykey", "t": "device1"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 166" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "undeploy_device", "params": {"c": "PORT=2,ID=5", "k": "mykey", "t": "device1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "undeploy_device",
  "params": {
    "c": "PORT=2,ID=5",
    "k": "mykey",
    "t": "device1"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:166 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '166', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'undeploy_device', 'params': {'c': 'PORT=2,ID=5', 'k': 'mykey', 't': 'device1'}})

response

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

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

Parameters:

  • k API key with allow=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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 188
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "update_device",
    "params": {
        "c": "PORT=2,ID=5",
        "k": "mykey",
        "save": "true",
        "t": "device1"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 188" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "update_device", "params": {"c": "PORT=2,ID=5", "k": "mykey", "save": "true", "t": "device1"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 188" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "update_device", "params": {"c": "PORT=2,ID=5", "k": "mykey", "save": "true", "t": "device1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "update_device",
  "params": {
    "c": "PORT=2,ID=5",
    "k": "mykey",
    "save": "true",
    "t": "device1"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:188 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '188', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'update_device', 'params': {'c': 'PORT=2,ID=5', 'k': 'mykey', 'save': 'true', 't': 'device1'}})

response

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

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

Parameters:

  • k API key with allow=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