LM API

Logic Manager LM API is called through URL request

http://<IP_address_LM:Port>/lm-api/function

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

All functions can be called using GET and POST methods. When POST method is used, the parameters can be passed to functions either as www-form or as JSON.

Note

Object creation and modification functions don’t save configurations automatically unless you specify save parameter in API request. The system is designed to work this way to let you discard the changes in case of serious problems by killing the controller process.

If you need to save any changes made without this parameter, restart the controller gracefully or use SYS API save function.

Contents

test - test API/key and get system info

Test can be executed with any valid API KEY

Parameters:

  • k valid API key

Returns JSON dict with system info and current API key permissions (for masterkey only ‘master’:true is returned)

{
    "acl": {
        "allow": {
            "cmd": true
        },
        "groups": [
            "system/#",
            "service",
            "security/+"
        ],
        "items": [],
        "key_id": "key1",
        "master": false,
        "sysfunc": false
    },
    "product_build": 2017082101,
    "product_code": "lm",
    "product_name": "EVA Logic Manager",
    "result": "OK",
    "system": "eva3-test1",
    "time": 1504489043.4566338,
    "version": "3.0.0"
}

Errors:

  • 403 Forbidden the key has no access to the API

state - get logic variable state

State of the lvar or all logic variables can be obtained using state command.

Parameters:

  • k valid API key
  • i lvar ID
  • g group filter, optional mqtt masks can be used, for example group1/#, group1/+/lamps)
  • full=1 display extended item info, optional (config_changed, description, virtual, status_labels and action_enabled for unit)

Returns lvar status in JSON dict or array of dicts:

[
    {
        "expires": 0,
        "full_id": "service/test",
        "group": "service",
        "id": "test",
        "set_time": 1506345719.8540998,
        "status": 1,
        "type": "lvar",
        "value": "33"
    }
]

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist, or the key has no access to the lvar

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.

Parameters:

  • k valid API key
  • i item ID, or multiple IDs, comma separated
  • a notifier ID which keeps history for the specified item(s) (default: db_1)
  • s time frame start, ISO or Unix timestamp
  • e time frame end, optional (default: current time), ISO or Unix timestamp
  • l limit history records (optional)
  • x item property (status or value)
  • t time format (iso or raw for Unix timestamp)
  • w fill frame with the specified interval (e.g. 1T - 1 minute, 2H - 2 hours etc.), optional
  • g output format, list (default) or dict

Returns state history for the chosen item(s) in the specified format.

To get state history for multiple items:

  • w param is required
  • g should be specified as list

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found item doesn’t exist, the key has no access to the item, or the history database is not found

set - set lvar state

Allows to set status and value of a logic variable.

Parameters:

  • k valid API key
  • i lvar id
  • s lvar status, optional
  • v lvar value, optional

Returns JSON dict result=”OK”, if the state is set successfully.

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist, or the key has no access to the lvar

reset - reset lvar state

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

Parameters:

  • k valid API key
  • i lvar id

Returns JSON dict result=”OK”, if the state is reset successfully.

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist, or the key has no access to the lvar

clear - clear lvar state

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

Returns JSON dict result=”OK”, if the state is cleared successfully.

Parameters:

  • k valid API key
  • i lvar id

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist, or the key has no access to the lvar

toggle - toggle lvar value

Allows to switch value of a logic variable between 0 and 1. Useful when lvar is being used as a flag to switch it between True/False.

Parameters:

  • k valid API key
  • i lvar id

Returns JSON dict result=”OK”, if the state is toggled successfully.

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist, or the key has no access to the lvar

groups - get lvar groups list

Get the list of the lvar groups. Useful i.e. for custom interfaces.

Parameters:

  • k valid API key

Returns JSON array:

[
    "parent_group1/group1",
    "parent_group1/group2"
]

Errors:

  • 403 Forbidden invalid API KEY

groups_macro - get macro groups list

Get the list of macro groups.

Parameters:

  • k valid API key

Returns JSON array:

[
    "parent_group1/group1",
    "parent_group1/group2"
]

Errors:

  • 403 Forbidden invalid API KEY

list_macros - get macro list

Get the list of all available macros.

Parameters:

  • k valid API key
  • g filter by group, optional (MQTT masks may be used, i.e. group1/#, group1/+/service)

Returns JSON array:

[
    {
       "action_enabled": true,
       "description": "description",
       "full_id": "group/macro_id",
       "group": "group",
       "id": "macro_id",
       "oid": "lmacro:group/macro_id",
       "type": "lmacro"
    }
]

Errors:

  • 403 Forbidden invalid API KEY

run - execute macro

Executes a macro with the specified arguments.

Parameters:

  • k valid API key
  • i macro id

optionally:

  • a macro arguments, space separated
  • p queue priority (less value - higher priority, default 100)
  • u unique action id (use this option only if you know what you do, the system assigns the unique ID by default)
  • w the API request will wait for the completion of the action for the specified number of seconds
  • q timeout (sec) for action processing in the public queue

Returns JSON dict with the following data (time** UNIX_TIMESTAMP):

{
   "err": "<compilation and exec errors>",
   "exitcode": <exit_code>,
   "item_group": "<group>",
   "item_id": "<macro_id>",
   "item_type": "lmacro",
   "out": "[macro out variable]",
   "priority": <priority>,
   "status": "<action status>",
   "time": {
       "created": <creation_time>,
       "pending": <public_queue_pending_time>,
       "queued": <controller_queue_pending_time>,
       "running": <running_time>
   },
   "uuid": "unique_action_id"
}

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found macro doesn’t exist, or the key has no access to the macro

In case the parameter w is not indicated or action is not finished in the specified time, it should continue running, and its status may be checked in accordance with assigned uuid. If action is terminated, exit code will stand for the exit code of the macro. Additionally, time will be supplemented by completed, failed or terminated. out field contains the output of out variable (if it was associated with a value in the macro), err field (in case of macro compilation/execution errors)contains the error details.

result - macro execution result

Get macro execution results either by action uuid or by macro id.

Parameters:

  • k valid API key

optionally:

  • i macro_id
  • u action uuid (either action uuid or macro_id must be specified)
  • g filter by macro group
  • s filter by action status (Q - queued, R - running, F - finished)

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found macro or action doesn’t exist, or the key has no access to the macro

Actions remain in the system until they receive the status completed, failed or terminated and until keep_action_status time indicated in controller configuration passes.

Note

This function doesn’t return results of the unit actions executed by macros

list - get list of all logic variables

Parameters:

  • k masterkey API key
  • g filter by group (optional)

Returns JSON array which contains lvars:

[
    {
       "description": "description",
       "expires": 0,
       "full_id": "group/id",
       "group": "group",
       "id": "lvare_id",
       "oid": "lvar:group/id",
       "set_time": 9999999,
       "type": "lvar"
    }
]

Errors:

  • 403 Forbidden invalid API KEY

get_config - get logic variable configuration

Parameters:

  • k masterkey
  • i lvar id

Returns complete lvar configuration.

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist

save_config - save lvar configuration on disk

Saves lvar configuration on disk (even if it wasn’t changed)

Parameters:

  • k masterkey
  • i lvar id

Returns JSON dict result=”OK”, if the configuration is saved successfully.

Errors:

  • 403 Forbidden invalid API KEY

list_props - get editable lvar parameters

Allows to get all editable parameters of the lvar configuration.

Parameters:

  • k masterkey
  • i lvar id

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found lvar doesn’t exist

set_prop - set item parameters

Allows to set configuration parameters of the lvar.

Parameters:

  • k masterkey
  • i lvar id
  • p lvar configuration param
  • v param value

Returns result=”OK” if the parameter is set, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

create_lvar - create new lvar

Creates new lvar.

Parameters:

  • k masterkey
  • i lvar id
  • g lvar group

optionally:

  • save=1 save lvar configuration on the disk immediately after creation

Returns result=”OK” if the lvar is created, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

destroy_lvar - delete lvar

Deletes lvar.

Parameters:

  • k masterkey
  • i lvar id

Returns result=”OK” if the lvar is deleted, or result=”ERROR”, if an error occurred.

LVar configuration can be immediately deleted from the disk, if there is db_update=instant set in controller configuration, at the moment of shutdown, if there is db_update=on_exit, or when calling SYS API save (or save in LM EI), if there is db_update=manual.

If configuration is not deleted by either of these, you should delete it manually by removing the file runtime/lm_lvar.d/ID.json, otherwise the lvar(s) will remain in the system after restarting the controller.

Errors:

  • 403 Forbidden invalid API KEY

list_macro_props - get editable macro parameters

Allows to get all editable parameters of the macro configuration.

Parameters:

  • k masterkey
  • i macro id

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found macro doesn’t exist

set_macro_prop - set macro parameters

Allows to set configuration parameters of the macro.

Parameters:

  • k masterkey
  • i macro id
  • p macro configuration param
  • v param value

Returns result=”OK” if the parameter is set, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

create_macro - create new macro

Creates new macro. Macro code should be put in xc/lm manually.

Parameters:

  • k masterkey
  • i macro id
  • g macro group

optionally:

  • save=1 save macro configuration on the disk immediately after creation

Returns result=”OK” if a macro is created, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

destroy_macro - delete macro

Deletes macro.

Parameters:

  • k masterkey
  • i macro id

Returns result=”OK” if the macro is deleted, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

list_rules - get rules list

Get the list of all available decision rules.

Parameters:

  • k valid API key

Returns JSON array of rules and their properties.

Errors:

  • 403 Forbidden invalid API KEY

list_rule_props - get editable rule parameters

Allows to get all editable parameters of the decision rule.

Parameters:

  • k masterkey or a key with allow=dm_rule_props to access in_range_*,_**enabled** and chillout_time rule props, or with an access to a certain rule by ID
  • i rule id

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found rule doesn’t exist

set_rule_prop - set rule parameters

Allows to set configuration parameters of the rule.

Parameters:

  • k masterkey or a key with allow=dm_rule_props to access in_range,_*enabled and chillout_time rule settings, or with an access to a certain rule
  • i rule id
  • p rule configuration param
  • v param value

Returns result=”OK” if the parameter is set, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

create_rule - create new rule

Creates new decision rule. Rule id is always generated automatically.

Parameters:

  • k masterkey

optionally:

  • save=1 save rule configuration on the disk immediately after creation

Returns result=”OK” if a rule is created, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

destroy_rule - delete rule

Deletes decision rule.

Parameters:

  • k masterkey
  • i rule id

Returns result=”OK” if the rule is deleted, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

list_remote - get a list of items from connected UCs

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

Parameters:

  • k masterkey

optionally:

  • g item group
  • p item type (U for unit, S for sensor)

Returns the JSON array of units and sensors loaded from the remote controllers. Additional field controller_id is present in any item indicating the controller it’s loaded from.

Errors:

  • 403 Forbidden invalid API KEY

list_controllers - get controllers list

Get the list of all connected UC controllers.

Parameters:

  • k valid API key

Returns JSON array:

[
    {
    "build": "BUILD",
    "connected": true,
    "description": "<controller_description>",
    "full_id": "<uc/controller_id>",
    "group": "uc",
    "id": "<controller_id>",
    "oid": "<remote_uc:uc/controller_id>",
    "type": "remote_uc",
    "version": "VERSION"
    }
]

Errors:

  • 403 Forbidden invalid API KEY

test_controller - test connection to remote controller

Allows to test connection to the UC controller.

  • k masterkey
  • i controller id

Returns result=”OK” if the test is passed, or result=”ERROR”, if failed.

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found controller doesn’t exist

list_controller_props - get editable controller parameters

Allows to get all editable parameters of the connected UC controller.

  • k masterkey
  • i controller id

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Not Found controller doesn’t exist

set_controller_prop - set controller parameters

Allows to set configuration parameters of the connected UC.

Parameters:

  • k masterkey
  • i controller id
  • p controller configuration param
  • v param value

Returns result=”OK” if the parameter is set, or result=”ERROR”, if an error occurs.

Errors:

  • 403 Forbidden invalid API KEY

append_controller - connect remote UC

Connects remote UC controller to the local.

Parameters:

  • k masterkey
  • uri UC API uri (proto://host:port)
  • a remote controller API key ($key to use local key)

optionally:

  • m MQTT notifier to exchange item states in real time
  • s True/False (1/0) verify remote SSL certificate or pass invalid
  • t timeout (seconds) for the remote controller API calls
  • save=1 save connected controller configuration on the disk immediately after creation

Returns result=”OK” if the controller is connected, or result=”ERROR”, if an error occurred.

The remote controller id is obtained and set automatically according to its hostname or name field in the controller configuration. The remote controller id can’t be changed.

Errors:

  • 403 Forbidden invalid API KEY

remove_controller - disconnect UC

Disconnects the remote UC controller.

Parameters:

  • k masterkey
  • i controller id

Returns result=”OK” if the controller is disconnected, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

reload_controller - reload items from UC

Allows to immediately reload all the items and their status from the remote UC controller.

Parameters:

  • k masterkey
  • i controller id

Returns result=”OK” if the controller is deleted, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

list_ext - list loaded macro extensions

Returns a list which contains all loaded macro extensions.

Parameters:

  • k masterkey

Errors:

  • 403 Forbidden invalid API KEY

load_ext - load macro extension

Loads:doc:macro extension</lm/ext>.

Parameters:

  • k masterkey
  • i macro extension ID, required
  • m macro extension module, required
  • c macro extension configuration

Optionally:

  • save=1 save extension configuration after successful call

Returns a dict with information about extension if module is loaded, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

unload_ext - unload macro extension

Unloads macro extension.

Parameters:

  • k masterkey
  • i macro extension ID

Returns result=”OK” if module is unloaded, or result=”ERROR”, if an error occurred.

Errors:

  • 403 Forbidden invalid API KEY

get_ext - get loaded macro extension information

Returns a dict with information about macro extension

Parameters:

  • k masterkey
  • i macro extension ID

Errors:

  • 403 Forbidden invalid API KEY
  • 404 Forbidden macro extension not found
  • 500 Internal Error inaccessible macro extension

list_ext_mods - get list of available macro extension modules

Returns a list of all available macro extension modules.

Parameters:

  • k masterkey

Errors:

  • 403 Forbidden invalid API KEY

modinfo_ext - get macro extension module info

Returns a dict with information about macro extension module.

Parameters:

  • k masterkey
  • m macro extension module

Errors:

  • 403 Forbidden invalid API KEY
  • 500 Internal Error inaccessible macro extension module

modhelp_ext - get extension module usage help

Returns a dict with macro extension usage help.

Parameters:

  • k masterkey
  • m macro extension module
  • c help context (cfg or functions)

Errors:

  • 403 Forbidden invalid API KEY
  • 500 Internal Error inaccessible macro extension module

User authorization using login/password

Third-party apps may authorize users using login and password as an alternative for authorization via API key.

login - user authorization

Authorizes user in the system and and opens a new authorized session. Session ID is stored in cookie.

Attention! Session is created for all requests to API, even if login is not used; web-browsers use the same session for the host even if apps are running on different ports. Therefore, when you use web-apps (even if you use the same browser to simultaneously access system interfaces or other apps) each app/interface should be associated with different domains/alias/different host IP addresses.

Parameters:

  • u user name
  • p user password

Returns JSON dict { “result” “OK”, “key”: “APIKEY_ID” }, if the user is authorized.

Errors:

  • 403 Forbidden invalid user name / password

logout

Finishes the authorized session

Parameters: none

Returns JSON dict { “result” : “OK” }

Errors:

  • 403 Forbidden no session available / session is already finished

info - reserved

Internal function, reserved for future use.

Parameters: none (no API key required).

Returns: component information.