EVA ICS documentation
EVA ICS is a platform for automated control and monitoring systems development, for any needs, from home/office to industrial setups. It is completely free for non-commercial use as well as for commercial, on condition that enterprise integrates it on its own. The product is distributed as a free software and is available under Apache License 2.0.
Automated control systems are facing a new stage of evolution: IoT-devices become interesting for those, who have never dealt with automation, cheap programmable devices become reliable enough for industrial use, commercial solutions move away from old protocols and involve computer networks instead. We do not reform automation – we change the approach: taking the classical technology as a basis, we simplify everything else to the maximum. Automation is simple and available for everyone!
What is EVA
- Universal controllers for management and monitoring of all your equipment, on the basis of which you can develop your own automation applications easily and quickly.
- Notification system, that instantly informs applications on current events.
- Logic Manager programming logic controllers used for automatic data processing and decision-making.
- EVA JS Framework and SFA Templates, allowing quick development of the interfaces for a specific configuration.
EVA can be installed either partially or fully, it can be scaled up to many servers or all components can be installed onto the only one. The system is designed in such a way, that it can work on any hardware: from fat servers to mini-computers with only one smart card in the “read-only” mode.
Architecture of EVA provides a high scalability: one system can support dozens and even hundreds of thousands of devices through processing events via separate subsystems and collecting all data to a unified database.
The latest EVA ICS version is 3.2.3. CHANGELOG
What you get with EVA
- powerful command-line interface (CLI)
- use pre-made drivers or write simple scripts for your automation hardware and keep them organized, queued and safely executed with Universal Controller
- easily collect data from the hardware using MQTT or SNMP traps with the built-in SNMP trap handler server
- collect data from your microcontrollers with a simple UDP API
- test and monitor the initial setup with controllers’ EI web interfaces
- exchange all automation data between multiple servers with EVA controllers and your own apps via MQTT server or JSON notifiers
- use EVA Logic Manager to write powerful macros which can be run automatically on events in accordance with the decision rules you set up
- collect everything and control your whole setup with the aggregator controllers
- API Clients to quickly connect controllers’ API to your apps
- develop a modern real-time websocket-powered SCADA web applications with EVA JS Framework
- set up IoT cloud with nodes connected via MQTT
- and much more
Installation
All you need to install EVA is to download the latest update from https://www.eva-ics.com/, unpack the archive to any folder and everything is almost ready to use.
Note
Each EVA ICS installation (node) can run multiple components. Despite they share node resources, they still act as independent processes and require inter-connection set up.
Contents
System Requirements
Important
Before installation, set the proper host name. It will be used to identify node controllers. Changing host name later will require manually removing/appending all static links between EVA ICS controllers.
- Python version 3 (3.4+)
- Python virtual environment modules (python3-virtualenv)
- Linux or UNIX-compatible system
- For SFA PVT to work with images: libjpeg-dev and libjpeg8-dev (for PIL / pillow installation)
- realpath (available in all modern Linux distributions)
- EVA ICS can run on any Linux or UNIX-compatible system, but for the smooth install we recommend Ubuntu or Debian.
- Install system package libow-dev to let EVA ICS install owfs module.
- To sync item status between the controllers in different networks - MQTT-server (e.g. mosquitto) or to communicate with other equipment and 3rd party software.
Warning
Installation scripts try to install all required Python modules automatically, but some of them can have problems installing with pip - install can fail or be slow. It’s better to install these modules manually, before running EVA installation scripts. Currently the problems can be expected on ARM systems with:
- pandas (python3-pandas)
- cryptography (python3-cryptography)
To let EVA ICS venv use system site modules, read instructions below.
Optional modules (can be disabled in venv configuration):
Using installer
Supported Linux distributions:
- Debian/Ubuntu/Raspbian
- Fedora
Automatic and unattended
Install required system packages, setup EVA ICS components:
sudo -s
curl geteva.cc | sh /dev/stdin -a
Customized
Customize API keys:
sudo -s
curl geteva.cc | env MASTERKEY=123 DEFAULTKEY=qwerty sh /dev/stdin -a
More options, interactive setup:
sudo -s
curl geteva.cc -o install.sh
sh install.sh --help
E.g. install required system packages, setup Universal Controller only, use external MQTT server and predefined API keys:
sudo -s
curl geteva.cc | \
env MASTERKEY=mykey DEFAULTKEY=mydefaultkey sh /dev/stdin \
--autostart --logrotate --bash-completion \
-- --auto -p uc --mqtt eva:password@192.168.1.100 --mqtt-announce --mqtt-discovery
Manual installation
Note
If you are going to run any controllers under restricted user account, make sure it has a valid shell set.
Preparing the system
Install required system packages and heavy Python modules from the OS repository. here is an example how to install them on Debian-based Linux (i.e. Ubuntu):
apt install -y curl gcc python3 python3-dev python3-virtualenv python3-distutils jq libow-dev libjpeg-dev libjpeg8-dev
Configuring MQTT broker
MQTT broker is used when EVA ICS controllers are located in different networks and can not exchange data with P2P connections.
Note
Starting from EVA ICS 3.2.3, MQTT broker for inter-connection of controllers which run on a single host/network is no longer required.
If EVA ICS node is already set up without MQTT configuration, you can add it later with easy-setup or manually, using eva ns command.
Installing local MQTT server
If you plan to use local MQTT server, here is an example how to install mosquitto MQTT server on Debian-based Linux (i.e. Ubuntu):
apt install -y mosquitto
# stop mosquitto
/etc/init.d/mosquitto stop
# let the server listen to localhost only
echo "bind_address 127.0.0.1" >> /etc/mosquitto/mosquitto.conf
# start mosquitto back
/etc/init.d/mosquitto start
# make sure mosquitto is running
ps auxw|grep mosquitto
Options for EVA ICS:
- MQTT host: localhost
- MQTT port: 1883 (default)
- MQTT user, password: leave empty
- MQTT space: leave empty
- MQTT SSL: leave empty (answer ‘n’ if using easy-setup)
Using AWS IoT as MQTT broker
Instead of setting up dedicated MQTT server, you can use cloud-based service, e.g. AWS IoT.
Note
Cloud IoT services provide restricted broker functionality and don’t guarantee event/message ordering. This means some state messages between controllers may be lost (discarded by controller core if newer message with the same topic is already received).
- Create AWS IoT Core “thing”
- Apply the following policy:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action":["iot:*"],
"Resource": ["*"]
}]
}
Options for EVA ICS:
- MQTT host: AWS IoT endpoint host (XXXXXXXXX.iot.XXXXXXXXX.amazonaws.com)
- MQTT port: 8883
- MQTT user, password: leave empty
- MQTT space: leave empty
- MQTT SSL: should be enabled (answer ‘y’ if using easy-setup; when notifier is configured later, SSL is automatically enabled as soon as ca_certs property is set)
- MQTT CA file, cert file, key file: provided by AWS (use private key file as key file)
- Disable MQTT retain (answer ‘y’ in easy-setup) to make sure no topics with retain flag will be sent to MQTT broker (otherwise EVA ICS controller will be instantly disconnected)
- Use MQTT QoS 0 or 1 (default)
- It’s recommended to create “things” for each EVA ICS controller. After setup, MQTT cert file and key file can be changed with CLI (eva ns [controller_type]…). Don’t forget to restart the controller to apply notifier configuration.
Downloading and extracting EVA ICS distribution
Go to EVA ICS website, download most recent distribution and unpack it e.g. to /opt/eva:
cd /opt
curl https://get.eva-ics.com/3.x.x/stable/eva-3.x.x-xxxxxxxxxx.tgz -o eva.tgz
tar xzvf eva.tgz
mv eva-3.x.x eva
cd eva
Customizing Python virtual environment
Starting from 3.2.1, EVA ICS uses Python virtual environment (venv). This makes software installation more stable, as it uses only tested versions of 3rd party libraries.
EVA ICS installation script automatically creates Python virtual environment in ./python3 folder. It can be customized/recreated later manually, using command:
./install/build-venv
If you want to rebuild venv from scratch, delete python3 folder completely.
On some systems (e.g. ARM-based computers) venv installation can be tricky: you can expect slow installation time or problems with some heavy modules (e.g. pandas, cryptography).
To solve this:
If you already run the installation and it has failed, delete ./python3 folder.
Go to ./etc folder, copy venv-dist to venv and customize virtual environment options.
- USE_SYSTEM_PIP=1 allows to use system-installed pip3 (apt-get install python3-pip) in case installation script has a problems downloading / installing it.
- SYSTEM_SITE_PACKAGES=1 virtual environment will use system site packages if their versions match with requested.
- SKIP here you can specify the packages (in quotes, space separated), which should be skipped (e.g. pandas cryptography and install it with apt-get install python3-pandas python3-cryptography instead). To let venv use system package, SYSTEM_SITE_PACKAGES=1 should also be present.
- EXTRA extra modules to install, e.g. required by PHIs, used by logic macros or macro extensions etc.
- PIP_EXTRA_OPTIONS specify extra options for pip3, e.g. -v for verbose installation.
Note
Customize venv only if you have serious problems installing EVA ICS with default options, as the system may became unstable when versions of 3rd party libraries are different from tested.
Options, specified in ./etc/venv are also used by EVA ICS update scripts, which check/rebuild venv on every system update.
Installing
Warning
If you want to run some components under restricted users, create var and log folders in EVA installation dir and make sure the restricted users have an access to these folders before running easy-setup. If you’ve customized ini files in etc, make sure the restricted user has an access to both <component>.ini and <component>_apikeys.ini.
If you want to make some initial customization, e.g. name the controllers different from the host name, make changes in etc/uc.ini, etc/lm.ini and etc/sfa.ini configs first.
- For the interactive setup, run ./easy-setup in EVA folder and follow the instructions.
- For the automatic setup, run ./easy-setup -h in EVA folder and choose the installation type.
Setup log rotation by placing etc/logrotate.d/eva-* files to /etc/logrotate.d system folder. Correct the paths to EVA files if necessary.
cp ./etc/logrotate.d/eva-* /etc/logrotate.d/
Setup automatic launch at boot time by placing EVADIR/sbin/eva-control start command into system startup e.g. either to /etc/rc.local on System V, or for systems with systemd (all modern Linux distributions):
cp ./etc/systemd/eva-ics.service /etc/systemd/system/
systemctl enable eva-ics
Updating
Warning
Before updating from the previous version, read update manifest.
Using EVA Shell
- Backup everything in system shell
- Launch EVA Shell (/opt/eva/bin/eva-shell or eva -I)
- Backup configuration (type backup save command in EVA Shell)
- Type update command in EVA Shell
Note
EVA ICS repository URL has been changed to https://get.eva-ics.com. If you’ve got “Update completed” message but update process hasn’t even been started, try executing update command specifying EVA ICS repository directly:
update -u https://get.eva-ics.com
Using system shell
- Backup everything
- Run the following command:
curl -s <UPDATE_SCRIPT_URL> | bash /dev/stdin
#e.g.
#curl -s https://get.eva-ics.com/3.2.0/stable/update.sh | bash /dev/stdin
- If updating from 3.0.2 or below, you may also want to enable controller watchdog (copy etc/watchdog-dist to etc/watchdog and edit the options if required)
Note
The system downgrade is officially not supported and not recommended.
Intermediate versions
It is usually absolutely safe to update old EVA ICS installations to newer version without applying all intermediate updates.
However, it is highly recommended to read update manifests for all skipped versions and combine before / after update instructions.
Moving to another folder
EVA ICS doesn’t depend on any system paths, this allows to easy rename or move its folder or clone the installation. Just do the following:
- stop EVA ICS (./sbin/eva-control stop)
- rename, move or copy EVA ICS folder
- if you’ve copied the folder, edit configuration files to make sure components use different ports and/or interfaces
- start EVA ICS back (./sbin/eva-control start)
- correct logrotate and on-boot startup paths
Watchdog
Watchdog process is started automatically for each EVA controller and tests it with the specified interval. Controller should respond to API call test within the specified API timeout or it is forcibly restarted.
Watchdog configuration is located in file etc/watchdog and has the following params:
- WATCHDOG_INTERVAL checking frequency (default: 30 sec)
- WATCHDOG_MAX_TIMEOUT maximum API timeout (default: 5 sec)
- WATCHDOG_DUMP if the controller is not responding, try to create crash dump before restarting (default: no).
How to assign IDs to items
All system items including macros have their own ids. Item id should be unique within one server in simple layout. When using enterprise layout, it is possible for items to have the same id in different groups, however full item id (group/id) should be always unique within one controller.
Note
Before adding items, consider what kind of layout you want to use: simple or enterprise
Starting from 3.2.0, default item layout is enterprise.
Item groups can coincide and often it is convenient to make them similar: for example, if you set groups=security/# in API key config file, you will allow the key to access all the items in the security group and its subgroups regardless of whether it is macro, sensor or logic variable. To set access to a group of particular items, use oids, e.g. groups=sensor:security/#.
This does not apply to decision rules and macros: a unique id is generated for each rule automatically, macro id should be always unique.
Note
The triple underline (___) is used by system and should not be used in item IDs or groups.
Log file customization
Perform these on the installed Python modules to avoid any extra information in logs:
dist-packages/ws4py/websocket.py and dist-packages/ws4py/manager.py - replace all logger.error calls to logger.info
dist-packages/urllib3/connectionpool.py - if you set up the controllers to bypass SSL verifications (don’t do this on production!), remove or comment
if not conn.is_verified:warnings.warn((….
Using NGINX as a frontend for SFA interface
External authentication
Suppose NGINX operates on 8443 port with SSL, and SCADA Final Aggregator - without SSL. Let’s make the task even more complicated: let NGINX receive the request not directly, but via port forwarding from the router listening on an external domain (i.e. port 35200).
Additionally, we want to authorize:
- by IP address or
- basic auth by username/password or
- by cookie-token (required for EVA Android Client since it passes basic auth only when the server is requested for the first time)
The server should allow access upon the authorization of any type.
Our final config for all of this should look like:
map $cookie_letmein $eva_hascookie {
"STRONGSECRETRANDOMTOKEN" "yes";
default "no";
}
geo $eva_ip_based {
192.168.1.0/24 "yes"; # our internal network
default "no";
}
map $eva_hascookie$eva_ip_based $eva_authentication {
"yesyes" "off"; # cookie and IP matched - OK
"yesno" "off"; # cookie matched, IP did not - OK
"noyes" "off"; # cookie did not match, IP did - OK
default "?"; # everything else - demand the password
}
upstream eva-sfa {
server 127.0.0.1:8828;
}
server {
listen 192.168.1.1:8443;
server_name eva;
ssl on;
ssl_certificate /opt/eva/etc/eva.crt;
ssl_certificate_key /opt/eva/etc/eva.key;
ssl_session_timeout 1m;
ssl_protocols SSLv3 TLSv1;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# proxy for HTTP
location / {
auth_basic $eva_authentication;
auth_basic_user_file /opt/eva/etc/htpasswd;
add_header Set-Cookie "letmein=STRONGSECRETRANDOMTOKEN;path=/";
proxy_buffers 16 16k;
proxy_buffer_size 16k;
proxy_busy_buffers_size 240k;
proxy_pass http://eva-sfa;
# a few variables for backend, though in fact EVA requires X-Real-IP only
proxy_set_header X-Host $host;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Frontend "nginx";
proxy_redirect http://internal.eva.domain/ui/ https://external.eva.domain:35200/ui/;
}
# proxy for WebSocket
location /ws {
auth_basic $eva_authentication;
auth_basic_user_file /opt/eva3/etc/htpasswd;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_buffers 16 16k;
proxy_buffer_size 16k;
proxy_busy_buffers_size 240k;
proxy_pass http://eva-sfa;
proxy_set_header X-Host $host;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Frontend "nginx";
}
}
Using HTTP basic auth for EVA ICS authentication
The following example demonstrates how to use basic authentication and automatically log in user into SFA UI.
Firstly, set user_hook option in ./etc/sfa.ini, this will allow EVA ICS to sync htpasswd file with SFA users (make sure htpasswd program is installed as well).
[server]
.......
user_hook = /opt/eva/xbin/htpasswd.sh /opt/eva/etc/htpasswd
Then, front-end config (e.g. for NGINX) should look like:
upstream eva-sfa {
server 127.0.0.1:8828;
}
server {
listen 80 default_server;
location / {
auth_basic $eva_authentication;
auth_basic_user_file /opt/eva/etc/htpasswd;
rewrite ^/pvt/(.+)$ /pvt?f=$1 last;
proxy_buffers 16 16k;
proxy_buffer_size 16k;
proxy_busy_buffers_size 240k;
proxy_pass http://eva-sfa;
proxy_set_header X-Host $host;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto http;
proxy_set_header X-Port $server_port;
proxy_set_header X-Frontend "nginx";
}
location /ws {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_buffering off;
proxy_pass http://eva-sfa;
proxy_set_header X-Host $host;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto http;
proxy_set_header X-Port $server_port;
proxy_set_header X-Frontend "nginx";
}
}
With such setup, EVA JS Framework-based interface doesn’t perform any authentication, $eva.start() function is called as soon as UI is loaded. API method login called by framework function will automatically log in user using basic authentication credentials provided to front-end server.
EVA ICS CHANGELOG
3.2.3 (2019-06-24)
Common
- MQTT server is not required anymore for local host/network installations, controllers can exchange information in real-time via P2P sockets (turned on automatically if MQTT server for controller is not specified).
- state_history method can now return chart image (SVG/PNG)
UC
- get_phi_ports API method - get ports of loaded PHI
- phi_discover API method - search for equipment supported by PHI module
- Modbus values reported to UC slave can now be automatically converted to signed and divided (or multiplied).
LM PLC
- set_job_prop macro function
- cycle can now run macros with args and kwargs
SFA
- easy-setup now creates default user (operator)
- “as” parameter for .json and .yml files changes their format on the flow
- JS SFA Framework is now deprecated. Use EVA JS Framework instead: https://github.com/alttch/eva-js-framework
3.2.2 (2019-05-21)
UC
- Driver API 5: “unload” method, unit values in PHIs.
LM PLC
- scheduled jobs
SFA
- evaHI integration
- transparent authentication on secondary UI pages
3.2.1 (2019-04-16)
Common
- fixes: small fixes in CLI
- fixes: code refactoring, performance optimization
- EVA ICS now loads 3rd party libraries from virtualenv which increases system stability as only tested version of libraries are used.
- Support for AWS IoT and Azure IoT
- Modbus slave register monitoring functions
- increment/decrement functions for lvars and shared macro variables
- read-only permissions for API keys
3.2.0 (2019-04-02)
Common
- Core, API and CLI performance improvements
- fixes: correct backup/restore if configuration folders are symlinks
- fixes: correct restore if –runtime flag is specified
- fixes: LM PLC locking problems
- notifier performance improvements
- CLI improvements
- personal Cloud support (nodes run API calls via MQTT)
- automatic node discovery
- license changed to Apache License 2.0
- new SYS API function: shutdown_core
- controller/node autodiscovery
- enterprise layout is now default item layout
- using item ids in API key properties is not allowed any longer in enterprise layout, item oid (type:group/id) must always be specified
- X-Auth-Key header authorization support
- JSON RPC 2.0 API
- JSON notifiers will send JSON RPC 2.0 notifications to the target uri, if method param is set
- RESTful API
- API session tokens
- Database support for MySQL and PostgreSQL
- supervisord support
UC
- warning: API function set_driver renamed to assign_driver
- new API functions: list_device_tpl, set_driver_prop, set_phi_prop
- 1-Wire OWFS support (virtual buses, PHIs), OWFS API functions
- Modbus slave support
- Driver API v4
LM PLC
- new API functions: enable_controller, disable_controller, matest_controller, set_ext_prop
- kwargs in macros (kwargs dict, plus all keyword arguments are available as variables)
- set_rule_prop now accepts “condition” and “for_oid”
- cycles, cycle control API and macro functions
- removed deprecated dm_rule* ACL
- removed deprecated get/post functions (use requests.get/post instead)
- Extension API v4
SFA
- new API functions: enable_controller, disable_controller, list_cycles
- SFA framework: code optimization, cycle states (warning: some functions are incompatible with previous version, use eva_sfa.3.1.js library or call the functions in new format only, look UPDATE.rst for more info)
- SFA framework: data exchange optimization with eva_sfa_state_updates variable
- removed deprecated dm_rule* ACL and rule control functions
- SFA templates: request now contains full request object
- SFA templates: new function api_call (call any SFA API method)
Deprecated (will be removed in 3.3.0)
- macro “argv” variable (replaced with “args”)
- PHP API client no longer supported (use JSON RPC)
- removed deprecated HTTP/POST and HTTP/GET notifiers
3.1.1 (2018-10-22)
Common
- fixes: interactive prompt behavior
- fixes: API client libs check result of “phi_test” and “phi_exec” functions
- history for interactive shell mode (to turn off set EVA_CLI_DISABLE_HISTORY=1 system environment variable)
- new management CLI: eva-shell (interactive by default)
- backup/restore operations (with eva-shell)
- dynamic API key management via CLI and API
UC
- fixes: device commands in enterprise layout
- performance improvements
- “update” command without params starts item passive update
- batch commands in UDP API (separated with new line)
- encryption and authentication in UDP API
- custom packet handlers in UDP API
- new API function: “test_controller”, detailed info in “list controllers”
- MQTT tools for PHIs
- test-phi CLI tool
LM PLC
- fixes: double quoted macro arguments in DM rules
- fixes: gain param in “tts” and “audio” extensions
- “action_toggle” macro func, “toggle” acts as an alias for unit oids
- “shared” and “value” macro funcs default return values
- new API function: “test_controller”, detailed info in “list controllers”
- new LPI: usp (unit single port)
- test-ext CLI tool
SFA
- new API function: “test_controller”, detailed info in “list controllers”
- SFA framework fixes and improvements
3.1.0 (2018-09-01)
UC drivers, device templates, state history, charts and other new features
Core
- working with locks now require allow=lock apikey permission
- new notifier type: db, used to store item state history
- SYS API functions: notifiers, enable_notifier, disable_notifier. the enable/disable API functions change notifier status only temporary, until the controller is restarted
- MQTT SSL support
- JSON notifiers. GET/POST notifiers are marked as deprecated and should not be used any more.
- exec function (cmd, run) string arguments split with ‘ ‘ now support the spaces inside (e.g. ‘this is “third argument”’)
UC
- new uc-cmd cli
- old uc-cmd renamed to uc-api
- UC drivers: logical to physical (LPI) and physical (PHI) interfaces
- native Modbus support (drivers only)
- device templates
- new function “state_history” in UC API
- EVA_ITEM_OID var in the environment of UC scripts
- action status label (case insensitive) may be used instead of number, if the label is not defined, API returns 404 error
- new key permission: “device”, allows calling device management functions.
- uc-tpl device template validator and generator (alpha)
- unit and sensor items now have physical location. If location is specified as coordinates (x:y or x:y:z), loc_x, loc_y and loc_z props become available
- UC EI now should be enabled/disabled in uc.ini
LM PLC
- new lm-cmd cli
- old lm-cmd renamed to lm-api
- macro extensions
- macro function “unlock” now return false if the lock hasn’t been locked or doesn’t exist
- unlock macro function may throw an exception if the controller forbids its functionality, in case the controller has no master key defined
- new functions “state_history” in LM API and “history” (equivalent) in macros
- new functions: status, value, nstatus, nvalue with oid support
- new DM rule events: on nstatus, nvalue change (for units)
- device management functions: “create_device”, “update_device”, “destroy_device”
- “set_rule_prop” macro function
- “alias” macro function
- rule filter in LM EI
- LM EI now should be enabled/disabled in lm.ini
SFA
- fixes: rule management functions
- new sfa-cmd cli
- sfa-cmd renamed to sfa-api
- new function “state_history” in SFA API and SFA Framework
- all functions now accept item oids
- “result” function returns the result of macro execution if macro action uuid or macro id (in the oid format) specified
- state API function accepts “full” parameter
- full SFA states now have item descriptions and status labels (for units)
- SFA API groups function now accept “g” parameter to filter group list (with MQTT-style wildcards)
- SFA rpvt function to load documents from remote servers
- SFA cvars are automatically available in SFA Framework app. Note: SFA cvars are public and may be obtained with any valid API key
- SFA Framework is now jQuery 3 compatible, included jQuery lib updated to 3.3.1
- SFA Framework item states now also have description and status labels fields
- eva_sfa_groups function, returns item groups list (with optional filter)
- eva_sfa_chart function, displays item state charts
- eva_sfa_popup function, displays popups and info windows
- new ws event: server restart and eva_sfa_server_restart_handler in a framework. SFA API function “notify_restart” allows to notify clients about the server restart w/o actual restarting (e.g. when restarting frontend)
- jinja2 templates for SFA ui and PVT files (all files with .j2 extension are served as templates). index.j2 has more priority than index.html
API Client
- new API function call result: “result_invalid_params” (11)
Common
- new notifier management CLI (old CLI tools available in legacy folder)
- watchdog to test/automatically restart controllers in case of failure
- oid support in API keys
- other stability improvements
3.0.2 (2018-06-23)
Bugfix release, some new urgent features, stability improvements
EVA documentation is now available in reStructuredText format and at https://eva-ics.readthedocs.io
Emergency interfaces
- fixes: correct display of long item names
- fixes: various bug fixes
- refresh buttons on item pages
- LM EI: reset button and expire timer in LM EI show/hide when prop changed
Core
- fixes: remove empty controller group when all objects are deleted
- fixes: remote items correctly display state in list_remote
- fixes: disabled sensors and lvars should not react to expiration
- each set_prop call now logs what’s actually changed
- added item oid (type:group/item_id) - reserved for the future releases
- added stop_on_critical option in config (default: yes), server will be restarted via safe-run if critical exception occur
- uptime in dump and test API function, last 100 exceptions are now stored in a dump, dumps are now compressed with gzip
- API functions now support JSON requests
UC
- action_toggle function to quickly toggle status of simple units
LM PLC
- list_remote returns array + controller_id property instead of dict
- result function in macro api. terminate and result function accept action uuid as a param
- on_set lm rule (status changed to 1)
- new LM API and macro functions: clear (set lvar value to 0), toggle (toggles lvar value between 0 and 1)
- cmd macro function now accepts full controller id (uc/controller_id) as well as short
- new macro functions for file management: ls, open_oldest, open_newest
SFA
- fixes: dm_rule_props acl in SFA
- list_remote returns array instead of dict + controller_id property
- list_macros contains now controller property
- append_controller now tries to autodetect controller type if no type is specified
- sfa pvt access logs
- reset, toggle, clear, action_toggle, result and terminate by uuid funcs in sfa & sfa framework
- reload_clients command and sfa framework reload event handler
- eva_sfa_expires_in function in a framework to work with timers
- log processing functions in a framework
- wildcard masks in eva_sfa_state and eva_sfa_register_update_state
Common
- easy-setup.sh - an interactive/automatic script to quickly set up the current host
- ability to run controllers under restricted user
3.0.1 (2018-02-21)
Minor release with some urgent features
Core
- EVA_ITEM_PARENT_GROUP variable in script ENV which contains the parent group of the item
- cvars now can be set as global or assigned to the specified item group i.e. ‘VAR1’ - global cvar, available to the all scripts, ‘group1/VAR2’ - variable available only to scripts from group ‘group1’ (as ‘VAR2’), ‘group2/VAR2’ - variable available only to group ‘group2’ (also as ‘VAR2’). Used by UC scripts to let one script manage different items
UC
- ‘update_delay’ prop - item passive update may start with a delay to prevent multiple updates running simultaneously producing high system load
- ‘clone’ function in UC API and uc-cmd to clone items
- ‘clone_group’ function - clones all matching items in a group
- ‘destroy_group’ function destroys all items in the specified group
LM PLC
- item id in LM rules match by simple mask (i.e. ‘*id’* or ‘id’* or ‘*id’)
3.0.0 (2017-10-19)
First public release
Security
Common recommendations
Traditionally, automation systems and protocols have been designed as not completely secure. As for reliability, you may agree that it would be a pity if the motor or door gets stuck because of incorrect access rights to a file or an expired SSL certificate.
Universal Controller, Logic Manager, SCADA Final Aggregator subsystems, as well as their interfaces, openly exchange API keys. If you do not use SSL, these keys can easily be caught. That is why only a separate secure network should be used to connect the controllers in the working configuration. Alternatively, you should install as many controllers as possible on the same server. Built-in web interfaces of the individual subsystems are called Emergency Interfaces. Therefore, they can only be used during primary setup, testing as well as in case of emergency but not on a regular basis.
All programs and extensions which use API calls should be connected at least via SSL or, ideally, in a separate secure network.
If you use secure networks or separate VLANs, it is not recommended to use SSL for API calls to avoid making setup complex and increasing load on your equipment.
Network design
The recommended enterprise configuration of the system is represented in the following scheme:
- Public network external network (company’s local network); applications working in a public network (usually SCADA interfaces), should be protected from unauthorized access as much as possible: they should use SSL and complex passwords and be regularly updated with the latest security patches.
- Supervisory network network accessed by authorized company employees only; it includes MQTT (event server), PLC (Logic Manager), custom automation applications and “public” interfaces of Universal Controller subsystems. The security policies are minimal. They are used not as means for protection against hacking, but rather for eliminating the possibility of component malfunction. Passwords/keys can be simple, pure HTTP without SSL can be used in order to reduce the load and avoid system failure because of incorrect certificates.
- Direct control network network in which only item management controllers operate, e.g. “productional” Universal Controller interfaces, TCP/IP-controlled relays, network sensor controllers etc.
In many setups, you may combine Supervisory network and Direct control network into a single network. As for security, this decision is not that bad, if the primary goal to divide these networks is comfortable maintenance.
Primary EVA interface is itself rather secure. Still, when connecting via insecure networks, especially via external Internet connection, it is highly recommended to:
- use frontend (NGINX, Apache)
- use SSL only (if frontend is present - use it for SSL processing)
- use firewall and forward only one port to the server with an interface
It is strongly recommended to access enterprise configurations with VPN only.
It is not recommended to keep debugging mode enabled in the production system, because some important data may be recorded in the log files.
Should I run it as root?
- Universal Controller is designed to be run on virtual machines, microcomputers, and embedded systems. If server directly controls connected devices, you should run it as root in order to avoid any device access errors. UC security bottleneck (when working under root) - API and UC EI interface. However, you should use API in Supervisory network only and UC EI interface should be turned off and used only in case of emergency.
- Logic Manager does not require direct access to the equipment, that is why it can be run as root on the selected system (if really required) or as a restricted user on the common-purpose servers. If Logic Manager API and interface are available only in Supervisory network, this issue is not critical for security.
- All external interfaces of the system, including SCADA Final Aggregator, should be run only under restricted users and protected with additional frontend and/or firewall.
API recommendations
X-Real-IP HTTP header
HTTP API uses X-Real-IP header variable to determine real IP address of client when working behind frontend. This can be used by attacker to compromise real IP address and bypass hosts_allow/hosts_assign key access control lists. Frontend should always clear X-Real-IP header variable and set it to the real ip of remote client.
X-Real-IP feature is disabled by default. To enable it, set param x_real_ip=yes in webapi section of controller configuration file.
Universal Controller API keys
- The key should contain at least 14 characters, including numbers, lowercase, and uppercase letters. Default keys generated during easy setup are random sha256 64-byte length hashes, which’s more than enough for security unless they’re transferred between controllers in an insecure network and sniffed.
- As far as day-to-day tasks are concerned, it is recommended to use API key masterkey (as well as all keys with master rights) only locally or for the system configuration/emergency situations.
- For the use of UC EI it is recommended to create operator key with groups = #, sysfunc = yes permissions.
- When connecting to Logic Manager and SCADA Final Aggregator it is recommended to create a separate key with rights for certain item groups, sysfunc = no, optionally allow = cmd.
- All external applications should have their own keys with restricted access rights to the required functions and items only.
- After installation, make sure that etc/uc_apikeys.ini file has 0600 permissions (and owned by the user you are running the controller under)
Logic Manager API keys
- After the initial configuration is complete, it is recommended to connect external applications only via keys with certain rights. Master key should not be used.
SCADA Final Aggregator interfaces
- If interface is available from within a public network, you should always use frontend with additional authentication
- Private data should be stored on SFA PVT server or protected in other way.
Common API security recommendations
If server is present in several VLANs, make sure that API listens only on Supervisory network address. If you do not use UDP API or SNMP traps in Universal Controller, disable them in the controller configuration. Do not enable the remote file control function unless it’s necessary for external apps.
Developer mode
Every component may be started in a “developer mode”: if enabled, all data, including API keys, is openly written in the log file. That is why we do not advise you to enable it unless you are our developer or integrator. Still, as far as the whole system code is open, you can try to enable it on your own responsibility. Never enable developer mode on the working system and avoid enabling debug mode as well.
If you contacted the product vendor or integrator who explained to you how to make a system “dump”, you should delete it from the system immediately after the file is no longer required. “dump” contains plenty of confidential data, including all API KEYS. Never give dump files to unauthorized persons! This is the same as giving away all configuration files, including the keys.
Dump file should be sent only via secure channels or in an encrypted form.
Notification system
The Notification System is embedded in all EVA subsystems. All the events of these subsystems are sent to the notification servers via objects called “notifiers” which contain the configuration of the notification endpoints.
Event structure
Each event includes the following data:
- Event subject (not to be confused with MQTT subject)
- Notification space May be used to divide the controlled structure into sectors, e.g. city1/office1, plant1 etc. By dividing spaces you can separate one EVA installation from another using the same notification server, e.g. to create your own multi-control and multi-monitoring systems.
- Event data (usually JSON dict with) data on what’s actually happened
Event subjects
There are several event subjects in EVA. Each notification endpoint can be subscribed either to one of them or to several ones.
state - item state change event
The event notifications with the “state” subject are sent by Universal Controller and Logic Manager whenever the items change their status.
Notification sends data similar to those, one can get using UC API or LM API state. There is one difference for a sensors:: sensor with error status (status = -1) does not send its value data until the value is null. This was done specifically for the logic components to work correctly with the old value until the sensor status data is updated correctly and the sensor is back online or until the data is expired.
action - unit and macro action events
Every time the unit action or macro action changes its status, the notification server receives “action” event notification.
Notification sends data similar to ones that can be obtained using UC API result command.
log - logged event
When the system or you add record to the logs, the notification system sends ‘log’ event notification. The log notification data have the following format:
{
"h": "<SYSTEM_NAME>",
"l": <LEVEL>,
"p": "<PRODUCT_CODE>",
"msg": "<message body>",
"mod": "<MODULE>",
"th": "<MODULE_THREAD>",
"t": <TIME(UNIX_TIMESTAMP)>
}
- SYSTEM_NAME the name specified in the configuration file of controller (or hostname by default)
- LEVEL 10 - DEBUG, 20 - INFO, 30 - WARNING, 40 - ERROR or 50 for CRITICAL
- PRODUCT_CODE “uc” for Universal Controller, “lm” for Logic Manager, “sfa” for SCADA Final Aggregator
- MODULE a specific system module, e.g. ‘unit’
- MODULE_THREAD the module thread, e.g. “_t_action_processor_lamp1”
Important: the system does not send the log records related to the notification system itself. They are not visible via EI interfaces and are written only into the local log files. This was done for the notification system not to send the records in cycles.
Configuring the notification endpoints
Configuration is done using the console commands uc-notifier for Universal Controller, lm-notifier for Logic Manager and sfa-notifier for SCADA Final Aggregator or eva ns <uc|lm|sfa>. Therefore, even if two controllers are set up in the same folder on the same server, they have different notification endpoints configurations.
Basic Configuration
Let’s play with notification system e.g. of Universal Controller. This command will give us the list of notifiers, including their types, IDs, status and endpoint target.
# eva ns uc list
Type ID Status Target mqtt eva_1 Enabled eva:test@localhost:1883/lab
Let’s test the endpoint (for mqtt the system will try to publish [space]/test)
# eva ns uc test eva_1 OK
To create the new notifier configuration, run:
eva ns uc create [-s SPACE] [-t SEC] [-y] ID PROPS
where
- ID the unique ID of the notifier
- PROPS endpoint properties, e.g. mqtt:[username:password]@host:[port]
- -s SPACE notification space
- -t SEC timeout (optional)
Option “-y” enables the notification configuration right after creation (by default all notifiers are created as disabled)
The notifier configuration params may be viewed with props and changed with set notifier CLI commands. To apply the changes you must restart the controller.
Except for endpoint configuration, notifiers have some additional params:
- skip_test if “true”, the endpoint won’t be tested at the controller start (the controller keeps the notifier active but puts error into the log)
- notify_key notification key for custom http endpoints
- collect_logs this should be set to “true” for SCADA Final Aggregator MQTT notifiers if you want to collect the logs of other controllers and have the records available locally in SFA.
Subscribing the notifier to events
By default, the new notifier is not subscribed to any events. You can review all the subscriptions using “get_config” command.
To subscribe notifier to the new subject, run:
eva ns uc subscribe <subject> <notifier_id> [args]
(where subject is “state”, “log” or “action”)
When subscribing notifier to logs, you may use optional -l LEVEL param (10 - DEBUG, 20 - INFO, default, 30 - WARNING, 40 - ERROR, 50 - CRITICAL).
When subscribing notifier to state changes, you may also always specify item types (comma separated) or use ‘#’ for all types with -v TYPE param, groups with -g GROUPS. Optionally you may specify the particular items to subscribe notifier to with -I ITEMS.
Note
For each “state” subscription you must specify either type and groups or item IDs.
Example:
eva ns uc subscribe state test1 -v ‘#’ -g ‘hall/#’
subscribes the notifier test1 to the events of the status change of all the items in the hall group subgroups.
Subscription to “action” requires the params similar to “state”. Additionally, -a ‘#’ should be specified to subscribe to all the action statuses or -a state1,state2,state3… to subscribe to the certain statuses of the queued actions:.
For example, the following command will subscribe the notifier to the events of all failed actions:
eva ns uc subscribe action test2 -v '#' -g '#' -a dead,refused,canceled,ignored,failed,terminated
Once created, the subscription can’t be changed, but new subscription to the same subject replaces the configuration of the previous one.
To unsubscribe the notifier from the subject, run:
eva ns uc unsubscribe [subject] <notifier_id>
If the subject is not specified, the notifier will be unsubscribed from all notification subjects.
The controller should be restarted to apply the new subscriptions configuration.
MQTT (mqtt)
MQTT is a major endpoint type used to link several EVA subsystems. For instance, it enables Logic Manager and SCADA Final Aggregator controllers to receive the latest item status from Universal Controller servers when set on a nodes in different networks. We test and use EVA with mosquitto server, but you can use any server supporting MQTT protocol. As far as MQTT is the major type of the EVA notification system, let us examine it in detailed.
MQTT and state notifications
Items in MQTT form a subject hive so-called “EVA hive”. Hive may have a space e.g. “plant1/” to separate several EVA systems which use the same MQTT server.
Item’s state is stored in a hive with the subject SPACE/item_type/group/item_id and contains the item state data and some configuration params in JSON array.
MQTT and action notifications
Unit action notifications are sent to the topic
SPACE/unit/group/UNIT_ID/action
Logic macros action notifications are sent to the topic
SPACE/lmacro/group/UNIT_ID/action
These messages include the serialized action information in JSON format. As soon as action state is changed, the new notification is sent.
MQTT and log notifications
Log messages are sent to the MQTT server as JSON with the following MQTT subject:
SPACE/log
It means that the common log subject is created for one EVA space.
Any EVA server (usually it’s a job for SCADA Final Aggregator) can be a log collector, collecting the reports from MQTT server (space/log), pass them further via the local notification system and have them available via API. In order to enable this function, set param collect_logs to true in the notifier configuration:
sfa-notifier set eva_1 collect_logs true
Setting up MQTT SSL
If MQTT server requires SSL connection, the following notifier properties should be set:
- ca_certs CA certificates file (e.g. for Debian/Ubuntu: /etc/ssl/certs/ca-certificates.crt), required. SSL client connection is enabled as soon as this property is set.
- certfile SSL certificate file, if required for authentication
- keyfile SSL key file for SSL cert
Setting up MQTT QoS
You may specify different MQTT QoS for events with different subjects.
To set the same QoS for all events, use command:
eva ns uc <notifier_id> set qos <Q>
(where Q = 0, 1 or 2)
To set QoS for the specified subject, use command:
eva ns uc <notifier_id> set qos.<subject> <Q>
e.g.
eva ns uc eva_1 set qos.log 0
Quick facts about MQTT QoS:
- 0 the minimum system/network load but does not guarantee message delivery
- 1 guarantees message delivery
- 2 the maximum system/network load which provides 100% guarantee of message delivery and guarantees the particular message has been delivered only once and has no duplicates.
Use MQTT for updating the item states
MQTT is the only EVA notifier type performing two functions at once: both sending and receiving messages.
Control and monitoring items can use MQTT to change their state (for synchronization) if the external controller can send active notifications under this protocol.
The items change their state to the state received from MQTT, if someone sends its state update to EVA hive with status or value subtopics. Setting item state with primary topic (using JSON dict) is not recommended.
To let the item receive MQTT state updates, set its mqtt_update configuration param to the local MQTT notifier ID, as well as additionally optionally specify MQTT QoS using a semicolon (i.e. eva_1:2). QoS=1 is used by default.
One item an be subscribed to one MQTT notifier to get the state updates, but different items on the same controller can be subscribed to different MQTT notifiers.
When remote controller is connected, Logic Manager and SCADA Final Aggregator have copies of the remote items and it’s better to sync them in real time. The MQTT notifier where state updates are received from is set in mqtt_update configuration param of the connected controller, the value mqtt_update_default from lm.ini/sfa.ini is used by default.
MQTT and unit actions
MQTT can be also used as API to send actions to the units. In order to send an action to the unit via MQTT, send a message with the following subject: [space]/<group>/<unit_id>/control and the following body:
status value priority
value and priority parameters are optional. If value should be omitted, set it to “none”.
In case you need 100% reliability, it is not recommended to control units via MQTT, because MQTT can only guarantee that the action has been received by MQTT server, but not by the target Universal Controller. Additionally, you cannot obtain action uuid and further monitor it.
To let unit responding to MQTT control messages, set its configuration param mqtt_control to the local MQTT ID. You may specify QoS as well via semicolon, similarly as for mqtt_update.
IoT Cloud setup
Special properties of MQTT notifiers allow to set up a cloud and connect EVA ICS nodes via MQTT instead of HTTP:
- announce_interval if greater than zero, controller will announce itself with a chosen interval (in seconds) via MQTT to other cloud members.
- api_enabled allows controller to execute API calls from other cloud members via MQTT.
- discovery enabled controller will connect other nodes in cloud as soon as discover them.
To use auto discovery feature, API key named default must be present and equal on all nodes.
API calls via MQTT are encrypted with AES-128-CBC, this allows to use any 3rd party MQTT servers without any risk.
Optionally, controller can be a member of different clouds via different MQTT notifiers.
DB Notifiers
EVA ICS has a special notifier type: db, which is used to store items’ state history. State history can be obtained later via API calls or EVA JS Framework for analysis and e.g. to build graphical charts.
To create db notifier, specify notifier props as db:<dbfile>[:keeptime], e.g. db:history1.db:604800, where history1.db - database file in runtime folder, 604800 - seconds to keep archive records (1 week). If keep time is not specified, EVA keep records for last 86400 seconds (24 hours).
After creating db notifier, don’t forget to subscribe it to state events. Events action and log are ignored.
If easy-setup is used for EVA installation, notifier called db_1 for SFA is created automatically.
History database format is sqlite3.
EVA ICS db notifiers work via SQL Alchemy, so MySQL and PosgreSQL data storage is also supported.
E.g. to use MySQL, specify db uri as:
mysql+pymysql://username:password@host/database
(pymysql Python module is required)
- or
- mysql+mysqldb://username:password@host/database
(mysqlclient Python module is required)
If you get “failed to create state_history table” error with MySQL/MariaDB, try setting:
set global innodb_file_format=Barracuda;
set global innodb_large_prefix=1;
set global innodb_default_row_format=dynamic;
or put these options to database server configuration file.
HTTP Notifiers
JSON
HTTP notifications (aka web hooks) can be transferred to servers which, for some reasons, cannot work with MQTT in real time, e.g. servers containing third-party or your own web applications.
JSON notifier send POST request to specified URI with data:
- k notification key the remote app may use to authorize the sender
- subject event subject
- data event data array
Your application must respond with JSON if the event has been processed successfully:
{ "ok" : true }
or if your app failed to process it:
{ "ok" : false }
or with HTTP status 202 (Accepted).
The event data field is always an array and may contain either one event or several ones.
When EVA controllers test remote http-json endpoint, they send notifications with subject=”test” and the remote app should always respond with { “ok”: True } and HTTP status 200 (OK).
Example of custom notification processing server with Python and Flask:
from flask import Flask, app, request, jsonify
app = Flask(__name__)
@app.route('/json', methods=['POST'])
def j():
data = request.json
# process notification request
return jsonify({'ok': True})
JSON RPC
If notifier method property is set to jsonrpc, JSON RPC 2.0 call is performed. For JSON RPC, errors must be specified in “error” field of the response. For successful calls, the “result” field in response may contain any data.
Example:
from flask import Flask, app, jsonify, request, abort, Response
app = Flask(__name__)
@app.route('/jsonrpc', methods=['POST'])
def jrpc():
payload = request.json
result = []
for p in payload if isinstance(payload, list) else [payload]:
if p.get('jsonrpc') != '2.0': abort(400)
r = None
if p.get('method') == 'notify':
data = p.get('params')
# process data
i = p.get('id')
if i:
r = { "jsonrpc": "2.0", "result": { "ok": True }, "id": i}
else:
i = p.get('id')
if i:
r = { "jsonrpc": "2.0", "error":
{ "code": 404, "message": "method not found" },
"id": i}
if not isinstance(payload, list):
result = r
else:
result.append(r)
if result:
return jsonify(result)
else:
return Response(None, 202)
Basic authentication
All HTTP notifiers support basic authentication. To start using it, set username and password notifier properties.
Command line interfaces
Contents
EVA command line apps
EVA apps are used to configure the system and call controller API functions from the command line or by external scripts. All of the following apps are located in bin folder.
EVA shell
EVA shell (eva-shell, eva -I or eva for single commands) is a primary CLI tool. It allows you to manage local system as well as calling other tools/subshells directly from CLI interactive command line.
With EVA shell you can install updates, backup and restore configuration, start and stop EVA components.
EVA shell provides commands for all EVA ICS API methods, auto completion for everything, command repeat, batch commands and is the recommended way to configure, manage and monitor EVA ICS nodes from command line.
with EVA shell, IoT management is a joy
Universal Controller
- uc-cmd manages Universal Controller (equal to eva uc)
- uc-notifier configures UC notification system (equal to eva ns uc)
- uc-tpl generate and validate device templates
Logic Manager
- lm-cmd manages Logic Manager (equal to eva lm)
- lm-notifier configures LM PLC notification system (equal to eva ns lm)
SCADA Final Aggregator
- sfa-cmd manages SCADA Final Aggregator (equal to eva sfa)
- sfa-notifier configures SFA notification system (equal to eva ns sfa)
Other
- test-uc-xc a special app to test UC item scripts. Launches an item script with UC cvars and EVA paths set in the environment.
- sbin/layout-converter allows to convert simple item layout to enterprise.
Device control apps
EVA distribution includes pre-installed samples for device controlling. All sample scripts are located in xbin folder
TCP/IP controlled relays
- EG-PM2-LAN controls EG-PM2-LAN Smart PSU
- SR-201 controls the SR-201 relay controllers - a quite popular and simple solution with TCP/IP management option
1-Wire (direct access via GPIO)
- w1_ds2408 controls Dallas DS2408-based relays on the local 1-Wire bus
- w1_therm monitors Dallas DS18S20, DS18B20 and other compatible temperature sensors on the local 1-Wire bus
- w1_ls displays the devices connected to the local 1-Wire bus
Tutorial
In this section, we will focus on EVA configuration which is illustrated by the following example.
There is a room and some equipment:
- Internal ventilation system, powered via SR-201 controlled relay, port 1
- External ventilation system, powered via SR-201 controlled relay, port 2
- Air temperature sensor Dallas DS18S20
- a motion sensor in the hall connected to AKCP SensorProbe
- a light in the hall connected to Denkovi SmartDEN IP-16R, port 2
- and some alarm system installed on a remote server and called by its own API (via GET request). As soon as the alarm is activated, it switches on the alarm siren and sends an SMS to the operator.
Our task is to automate the above:
- To switch on the internal ventilation every night for the period from 9pm till 7am.
- To switch on ventilation in the daytime, if the air temperature is above 25 degrees for more than 5 minutes in a row.
- If the sensor detects a motion, do the following:
- if the alarm is on - send an API request to the alarm system
- if the alarm is off - turn on the light in the hall
- The user should be able to control the ventilation system with web interface, see the temperature, manage alarm and lighting
Let’s do this step by step, from equipment configuration to interface development. Let’s Suppose that EVA has already been installed and everything is located on a single server, including MQTT server with eva:secret access and all the data will be sent into plant1 subject.
EVA bin folder is included in system PATH.
All operations will be done using command line applications.
Universal Controller configuration
- EVA Tutorial parts
- Intro
- Universal Controller configuration << we are here
- Logic Manager configuration
- SCADA Final Aggregator configuration
- Building an interface with EVA JS Framework
So, let us proceed with our configuration. Connect the equipment to Universal Controller and configure the notification system.
Contents
Connecting ventilation
create two units for ventilation:
eva uc create unit:ventilation/vi -y # internal
eva uc create unit:ventilation/ve -y # external
Method 1: with scripts
As a first step, create the variable for controlling SR-201 in order not to write the full relay control commands anew:
eva uc cvar set REL1_CMD "SR-201 192.168.22.3"
As far as both ventilation systems are connected via the same relay, and it displays the states of all ports at once, let’s create a multiupdate for updating their status with a single command:
eva uc create mu:ventilation/mu1 -y
eva uc config set mu:ventilation/mu1 items unit:ventilation/vi,unit:ventilation/ve
and the script for this multiupdate named xc/uc/mu1_update:
#!/bin/sh
${REL1_CMD} | head -2
Note
After creating a script file, don’t forget to set its executable permissions (chmod +x scriptfile)
Let’s check the script:
test-uc-xc xc/uc/mu1_update
Reading custom vars from /opt/eva/runtime/uc_cvars.json
REL1_CMD = "SR-201 192.168.22.3"
Starting 'xc/uc/mu1_update'
stime: 1507923323.396813
etime: 1507923323.400836
duration: 0.004023 sec ( 4.022598 msec )
exitcode: 0
---- STDOUT ----
0
0
---- STDERR ----
----------------
Then we need to create two scripts for the relay control.
For internal ventilation, named xc/uc/vi
#!/bin/sh
${REL1_CMD} 1 $2
and for external ventilation, named xc/uc/ve
#!/bin/sh
${REL1_CMD} 2 $2
Enable the ventilation control:
eva uc action enable unit:ventilation/vi
eva uc action enable unit:ventilation/ve
set a multiupdate to update unit states every 30 seconds
eva uc config set mu:ventilation/mu1 update_interval 30 -y
Method 2: with driver
Starting from EVA 3.1 you can use pre-made drivers. Let’s do the above with driver.
Download PHI module:
eva uc phi download https://get.eva-ics.com/phi/relays/sr201.py
Load PHI module to controller. As sr201 PHI provides aao_get feature, set update=30 to update all items which use drivers with this PHI every 30 seconds:
eva uc phi load relay1 sr201 -c host=192.168.22.3,update=30 -y
Let’s test it:
eva uc phi test relay1 self
After loading sr201 PHI automatically created driver “relay1.default” with “basic” LPI. As we have a simple logic, let’s use it as-is. Set driver to both ventilation units:
eva uc driver assign unit:ventilation/vi relay1.default -c port=1 -y
eva uc driver assign unit:ventilation/ve relay1.default -c port=2 -y
Connecting a temperature sensor
Create sensor in UC:
eva uc create sensor:env/temp1
(Consider Linux w1-gpio and w1-therm kernel modules are already loaded)
Let’s find our sensor on a 1-Wire bus:
./xbin/w1_ls
28-000006ef85d7
Method 1: with scripts
Here it is. Create a script named xc/uc/temp1_update
#!/bin/sh
VALUE=`w1_therm 28-000006ef85d7` && echo 1 ${VALUE} || echo -1
Let the temperature update every 20 seconds:
eva uc config set sensor:env/temp1 update_interval 20 -y
Method 2: with driver
Download PHI module:
eva uc phi download https://get.eva-ics.com/phi/sensors/env/w1_ds18n20.py
Load PHI module to controller. This is universal PHI which means you don’t need to specify particular sensor address when loading, it should be specified later when you set driver to sensor:
eva uc phi load w1t w1_ds18n20 -y
After loading w1_ds18n20 PHI automatically created driver “w1t.default” with “sensor” LPI. As we have a simple logic, let’s use it as-is. Set driver to sensor:
eva uc driver assign sensor:env/temp1 w1t.default -c port=28-000006ef85d7 -y
As this PHI doesn’t provide aao_get feature and we can’t ask it to update sensors automatically, set update_interval sensor property to let it passively update itself every 20 seconds:
eva uc config set sensor:env/temp1 update_interval 20 -y
Connecting a motion sensor
Create a sensor in UC:
eva uc create sensor:security/motion1 -y
and configure the sensors controller to send SNMP traps to our server IP.
Method 1: with SNMP trap parser
Switch on the debugging mode and look into the log file:
eva uc debug on
tail -f log/uc.log|grep "snmp trap data"
Let someone walk near the sensor and we’ll catch SNMP trap data:
2017-10-13 18:52:42,568 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.2.1.1.3.0 = 549411751
2017-10-13 18:52:42,569 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.4.1.3854.1.0.301
2017-10-13 18:52:42,571 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.18.1.3.0 = 192.168.22.95
2017-10-13 18:52:42,572 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.18.1.4.0 =
2017-10-13 18:52:42,574 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.1.1.4.3.0 = 1.3.6.1.4.1.3854.1
2017-10-13 18:52:42,576 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.1.0 = 4
2017-10-13 18:52:42,579 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.2.0 = 1
2017-10-13 18:52:42,581 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.3.0 = 0
2017-10-13 18:52:42,583 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.4.0 = 0
2017-10-13 18:52:42,584 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.5.0 = Motion1
2017-10-13 18:52:42,586 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.6.0 = MD Hall
2017-10-13 18:52:44,583 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.2.1.1.3.0 = 549411951
2017-10-13 18:52:44,584 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.1.1.4.1.0 = 1.3.6.1.4.1.3854.1.0.301
2017-10-13 18:52:44,586 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.18.1.3.0 = 192.168.22.95
2017-10-13 18:52:44,588 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.18.1.4.0 =
2017-10-13 18:52:44,589 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.6.3.1.1.4.3.0 = 1.3.6.1.4.1.3854.1
2017-10-13 18:52:44,591 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.1.0 = 2
2017-10-13 18:52:44,594 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.2.0 = 0
2017-10-13 18:52:44,596 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.3.0 = 0
2017-10-13 18:52:44,597 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.4.0 = 0
2017-10-13 18:52:44,598 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.5.0 = Motion1
2017-10-13 18:52:44,602 plant1 DEBUG uc traphandler_t_dispatcher: snmp trap data 1.3.6.1.4.1.3854.1.7.6.0 = MD Hall
As we can see, the sensor sends SNMP OID 1.3.6.1.4.1.3854.1.7.1.0 = 4 when there is some activity and 1.3.6.1.4.1.3854.1.7.1.0 = 2 when the activity is finished. If we disconnect the sensor from the sensorProbe, trap with the same OID and value 7 will be received.
switch off the debugging mode
eva uc debug off
append one ident var to let it parse only “its own” traps:
eva uc config set sensor:security/motion1 snmp_trap.ident_vars "1.3.6.1.4.1.3854.1.7.6.0=MD Hall" -y
and use SNMP OID 1.3.6.1.4.1.3854.1.7.1.0 to monitor it:
eva uc config set sensor:security/motion1 snmp_trap.set_down 1.3.6.1.4.1.3854.1.7.1.0=7 -y
eva uc config set sensor:security/motion1 snmp_trap.set_if 1,1:1.3.6.1.4.1.3854.1.7.1.0=4 -y
eva uc config set sensor:security/motion1 snmp_trap.set_if 1,0:1.3.6.1.4.1.3854.1.7.1.0=2 -y
The final sensor configuration will look like:
eva uc config get sensor:security/motion1
{
"description": "",
"expires": 0,
"mqtt_update": null,
"snmp_trap": {
"ident_vars": {
"1.3.6.1.4.1.3854.1.7.6.0": "MD Hall"
},
"set_down": {
"1.3.6.1.4.1.3854.1.7.1.0": "7"
},
"set_if": [
{
"status": 1,
"value": "1",
"vars": {
"1.3.6.1.4.1.3854.1.7.1.0": "4"
}
},
{
"status": 1,
"value": "0",
"vars": {
"1.3.6.1.4.1.3854.1.7.1.0": "2"
}
}
]
},
"update_exec": null,
"update_interval": 0,
"update_timeout": null,
"virtual": false
}
The sensor is ready. It doesn’t require any passive update script since its state is updated with SNMP traps by the equipment.
Method 2: with driver
Download PHI module:
eva uc phi download https://get.eva-ics.com/phi/sensors/alarm/akcp_md.py
Load PHI module to controller. Consider motion sensor is connected to AKCP sensor controller port #1 and it has IP address 192.168.22.5.
eva uc phi load md1 akcp_md -c host=192.168.22.5,sp=1 -y
If one port is specified, akcp_md creates a driver with ssp LPI, which doesn’t need any additional options. Just set it to our sensor:
eva uc driver assign sensor:security/motion1 md1.default -y
The sensor is ready. It doesn’t require any passive updates since its state is updated with SNMP traps parsed by driver.
Connecting a hall light
Create hall light unit:
eva uc create unit:light/lamp1 -y
eva uc action enable unit:light/lamp1
Let it turn off automatically after 10 mins of inactivity:
eva uc config set unit:light/lamp1 auto_off 600 -y
and enable the actions to be always executed:
eva uc config set unit:light/lamp1 action_always_exec 1 -y
Method 1: with scripts
So, now we have to connect the lamp to Denkovi IP-16R relay. Connect it similarly to ventilation:
eva uc cvar set REL2_CMD "snmpset -v2c -c private 192.168.22.4 .1.3.6.1.4.1.42505.6.2.3.1.3"
eva uc cvar set REL2_UPDATE_CMD "snmpget -v2c -c public 192.168.22.4 .1.3.6.1.4.1.42505.6.2.3.1.3"
This relay returns the status of each port separately. Additionally, there is only one connected device and, therefore, we won’t create a multiupdate for the unit and let it update the state with its own update script.
Create a script named xc/uc/lamp1_update
#!/bin/sh
${REL1_UPDATE_CMD}.1 | cut -d: -f2 | awk '{ print $1 }'
and the action script xc/uc/lamp1
#!/bin/sh
${RELAY1_CMD}.1 i $2
Let’s update the lamp state every 30 seconds:
eva uc config set unit:light/lamp1 update_interval 30 -y
Method 2: with driver
Download PHI module:
eva uc phi download https://get.eva-ics.com/phi/relays/dae_ip16r.py
Load PHI module to controller. This is universal PHI which means you don’t need to specify particular relay host when loading, it may be specified later when you set driver to sensor. But in our example we have only one relay of such type, so let’s specify all options in PHI config:
eva uc phi load relay2 dae_ip16r -c host=192.168.22.4,retries=2 -y
After loading dae_ip16r PHI automatically created driver “relay2.default” with “basic” LPI. As we have a simple logic, let’s use it as-is. Set driver to lamp unit:
eva uc driver assign unit:light/lamp1 relay2.default -c port=2 -y
Let’s update the lamp state every 30 seconds:
eva uc config set unit:light/lamp1 update_interval 30 -y
Now open UC EI, check the setup, switch on/off the units, see how the sensor values are updated.
API keys configuration
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
Connect Logic Manager and SCADA Final Aggregator to this controller. Create two API keys for them in etc/uc_apikeys.ini:
[lm]
key = secret_for_lm
groups = #
sysfunc = no
hosts_allow = 127.0.0.1
[sfa]
key = secret_for_sfa
groups = #
sysfunc = no
hosts_allow = 127.0.0.1
After adding the new keys, you need to restart UC, which we’ll do later. Firstly, you should connect it to MQTT.
Notification system configuration
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
To let the item states be transferred from UC to other controllers in real time, configure its notification system. Connect the server to the local MQTT:
eva ns uc create eva_1 mqtt:eva:secret@localhost -s plaint1 -y
eva ns uc subscribe state eva_1 -v '#' -g '#'
eva ns uc config eva_1
{
"enabled": true,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
}
],
"host": "localhost",
"id": "eva_1",
"password": "secret",
"space": "plant1",
"type": "mqtt",
"username": "eva"
}
Looks good. Now restart UC:
eva uc server restart
The configuration of Universal Controller is complete. Let’s proceed to Logic Manager configuration.
Logic Manager configuration
- EVA Tutorial parts
- Intro
- Universal Controller configuration
- Logic Manager configuration << we are here
- SCADA Final Aggregator configuration
- Building an interface with EVA JS Framework
So, let us proceed with our configuration. As soon as Universal Controller is already configured, let us move on with Logic Manager.
Contents
Configuring notification system and API key for SFA
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
The first step is to connect the server to the local MQTT to allow Logic Manager to receive UC item states in real time:
eva ns lm create eva_1 mqtt:eva:secret@localhost -s plant1 -y
then subscribe the notification system to receive the states of the local logic variables which will be created later:
eva ns lm subscribe state eva_1 -v lvar -g '#'
eva ns lm config eva_1
{
"enabled": true,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
}
],
"host": "localhost",
"id": "eva_1",
"password": "secret",
"space": "plant1",
"type": "mqtt",
"username": "eva"
}
Add API key for SCADA Final Aggregator in etc/lm_apikeys.ini:
[sfa]
key = secret_for_sfa2
groups = #
hosts_allow = 127.0.0.1
Restart LM PLC:
eva lm server restart
Connecting UC controller
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
Connect the local UC to Logic Manager using the key we’ve created in etc/uc_apikeys.ini in the previous part of the tutorial:
eva lm controller append http://localhost:8812 -a secret_for_lm -m eva_1 -y
eva lm -J remote -p S
[
{
"controller_id": "uc/uc1",
"group": "security",
"id": "motion1",
"oid": "sensor:security/motion1",
"status": 1,
"type": "sensor",
"value": "0"
},
{
"controller_id": "uc/uc1",
"group": "env",
"id": "temp1",
"oid": "sensor:env/temp1",
"status": 1,
"type": "sensor",
"value": "25.4"
}
]
Looks correct, sensors are loaded, let’s check the units:
eva lm remote -p U
Let LM PLC reload the items from the connected controller every 60 seconds, if new ones are added in future:
eva lm controller set uc1 reload_interval 60 -y
Building logic
We have two tasks: to switch on the inside ventilation if the temperature is above 25 degrees, and handle the events received from the motion sensor. Do not forget that the inside ventilation should be off from 9pm till 7am. Though this will be later implemented via eva sfa (sfa-cmd) and system cron, we should get it prepared now.
Ventilation logic
We chose our example, as far as the boundary conditions of the sensor is a very common problem for such tasks.
If we solve this problem by creating the following two rules:
- if the temperature is above 25 degrees, the fan is switched on
- if below - switched off
the following problem may occur: if the temperature will hover around 25 degrees, the ventilation system will constantly switch on and off. Therefore, a breakdown is highly possible. We cannot simply set up chillout_time in the rule, it completely disables the rule, so it doesn’t match after the chillout is over, if both previous and current state are in the range.
Due to the flexibility of EVA there is a number of solutions of this problem:
Option 1:
Ventilation is switched on, if the temperature is above 25 degrees, and switched off if it is below e.g. 25.5. The logic will have half a degree gap for the equipment not to be overloaded. If the temperature changes not that quickly, this option would be the best one.
Option 2:
- Create the rule without a condition activated whenever the env/temp1 sensor changes its value
- The stop-start logic, as well as the temperature monitoring logic, is fully transferred to the macro executed by the above rule.
- macro reads the value of lvar ventilation/start_temp (to avoid hardcoding 25 in a macro code and let it have an ability to be changed from outside)
- To avoid the continuous running of macro, use the rule prop chillout_time. Or even
- Use unit_status macro function to get the current ventilation status and use macro lock function to block its changing too often e.g. for 5 minutes
The macro code will look like:
if status('unit:ventilation/vi') and \
value('sensor:env/temp1') < value('ventilation/start_temp'):
try: lock('ventilation/vi/control', 5, 300)
except: exit()
stop('ventilation/vi')
elif not status('unit:ventilation/vi') and \
value('sensor:env/temp1') >= value('ventilation/start_temp'):
try: lock('ventilation/vi/control', 5, 300)
except: exit()
start('ventilation/vi')
Option 3
Increase update_interval prop of env/temp1 sensor e.g. to 300 seconds. This option will work, though it is not that good because the system will obtain the current temperature with a 5 min delay (or we need to duplicate the sensor in UC and create a quicker one).
Option 4
Add a 5 minutes delay at the end of xc/uc/vi action script, allow vi queues (set action_queue=1 unit prop), and start ventilation from the macro in the following way:
try: lock('ventilation-example3', 5, 10)
except: exit()
# clean up all queued action
q_clean('ventilation/vi')
# exec our action
start('ventilation/vi')
unlock('ventilation-example3')
Not bad, but we loose an ability to exec the actions with w param and get the correct completion status.
Option 5
Use system crontab to copy env/temp1 value to some logic variable every 5 minutes. Then work only with this logic variable. This option is too awkward, the logic of the system crontabs will sooner or later turn into the script hell. Therefore, we will use cron only for the time schedule-based logic, everything else will be done using EVA.
Option 6 - the best one
There are more than 10 options to solve our problem, but we will choose the best one: delayed start. Moreover, we have a condition to run ventilation only in 5 minutes after the temperature becomes >=25. So, we will use this option. The other ones have been reviewed just because this is a tutorial.
Create two logic variables:
eva lm create lvar:ventilation/vi_auto -y
eva lm create lvar:ventilation/vi_timer -y
eva lm set lvar:ventilation/vi_auto -s 1 -v 1
The first one will act as a flag for the ventilation control macro: if the flag is on 1, the control is possible, if off - the ventilation should not be touched. The second variable will act as a delayed start timer.
Create a control macro which satisfies for our current task and the scheduled ventilation switching. We will give it two parameters: the first - what to do with ventilation (0 - switch off, 1 - switch on), the second - who runs it: temperature event, our delayed start timer or a system cron:
eva lm macro create control/vi_control -y
Put a macro code in xc/lm/vi_control.py file
if _1: # if anyone asks to switch on the ventilation
if _2 == 'event': # if it's an event
reset('ventilation/vi_timer') # reset delayed start timer
elif _2 == 'timer': # if it's a timer
if value('ventilation/vi_auto'):
start('ventilation/vi') # start ventilation if allowed
elif _2 == 'cron': # if it's a system cron
# disable the ventilation automation for everyone but cron
clear('ventilation/vi_auto', 0):
start('ventilation/vi') # start ventilation
else: # if it's a command to switch off
clear('ventilation/vi_timer') # stop the delayed start timer
if value('ventilation/vi_auto') or _2 == 'cron':
# in case the command is send by cron or
# if allowed to stop - stop it
stop('ventilation/vi')
if _2 == 'cron':
# if the ventilation is switched off by cron
# then enable automation back for everyone
set('ventilation/vi_auto', 1)
The macro requires 3 rules:
The first one will match if the temperature is above or equal to 25 degrees and activates the delayed start timer:
eva lm -I
rule create
rule set <rule_uuid> oid sensor:env/temp1.value
rule set <rule_uuid> condition x >= 25
rule set <rule_uuid> macro vi_control
rule set <rule_uuid> macro_args "1 event"
The second one will match if the temperature is below 25 degrees and switches the ventilation off (if it’s allowed):
rule create
rule set <rule_uuid> oid sensor:env/temp1.value
rule set <rule_uuid> condition x < 25
rule set <rule_uuid> macro vi_control
rule set <rule_uuid> macro_args "0 event"
The third rule will run the macro to turn the ventilation on as soon as the delayed start timer finishes the countdown:
rule create
rule set <rule_uuid> oid lvar:ventilation/vi_timer.status
rule set <rule_uuid> condition x == -1
rule set <rule_uuid> macro vi_control
rule set <rule_uuid> macro_args "1 timer"
Motion sensor logic
We will need one variable identifying whether the alarm is switched on or not:
eva lm create lvar:security/alarm_enabled -y
eva lm set lvar:security/alarm_enabled -s 1 -v 0
Additionally, we will need two macros. The first one will send API call to alarm system:
eva lm macro create security/alarm_start -y
put its code to xc/lm/alarm_start.py:
# do not send API calls more than once in 30 minutes
try: lock('alarm-start', expires = 1800)
except: exit()
# call the alarm system API
requests.get('http://alarmserver/api/activate?apikey=blahblahblah')
The second one will check whether the alarm is switched, to either switch on the alarm system or just turn on the lighting:
eva lm macro create security/motion1_handler -y
put its code to xc/lm/motion1_handler.py:
if value('security/alarm_enabled'):
run('security/alarm_start')
else:
start('light/lamp1')
Plus the additional rule executing motion1_handler macro when the motion sensor detects an activity:
eva lm rule create
eva lm rule set <rule_uuid> oid sensor:security/motion1/value
eva lm rule set <rule_uuid> condition 'x=1'
eva lm rule set <rule_uuid> macro motion1_handler
eva lm rule enable <rule_uuid> -y
The logic is set up. We can review and test it in LM EI and configure SCADA Final Aggregator configuration to interact with the external applications (in our case - the system cron, for the scheduled ventilation control) and serve the system web interface.
SCADA Final Aggregator configuration
- EVA Tutorial parts
- Intro
- Universal Controller configuration
- Logic Manager configuration
- SCADA Final Aggregator configuration << we are here
- Building an interface with EVA JS Framework
So, let us proceed with our configuration. Universal Controller has already been set up and Logic Manager as well. Therefore, let us move on to SCADA Final Aggregator configuration.
Since the logic has already been implemented, we have only two tasks: to interconnect all the controllers and connect the system cron that will control the ventilation schedule.
Contents
Notification system configuration
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
The first step is to connect the server to the local MQTT to allow SCADA Final Aggregator to get the state of UC and LM PLC items in real time:
eva ns sfa create eva_1 mqtt:eva:secret@localhost -s plant1 -y
We won’t subscribe the notifier to anything, because all the data are received from it, and there is nothing to send instead.
eva ns sfa config eva_1
{
"enabled": true,
"host": "localhost",
"id": "eva_1",
"password": "secret",
"space": "plant1",
"type": "mqtt",
"username": "eva"
}
Restart SFA:
eva sfa server restart
Connecting controllers
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
The next step is to connect the local UC and LM PLC to SCADA Final Aggregator with the keys created specifically for SFA:
eva sfa controller append http://localhost:8812 -a secret_for_sfa -m eva_1 -y
eva sfa controller append http://localhost:8817 -a secret_for_sfa2 -m eva_1 -y
eva sfa -J remote -p S
[
{
"controller_id": "uc/uc1",
"group": "security",
"id": "motion1",
"oid": "sensor:security/motion1",
"status": 1,
"type": "sensor",
"value": "0"
},
{
"controller_id": "uc/uc1",
"group": "env",
"id": "temp1",
"oid": "sensor:env/temp1",
"status": 1,
"type": "sensor",
"value": "25.4"
}
]
Looks fine, sensors are loaded, let’s check units and logic variables:
eva sfa -J remote -p U
eva sfa -J remote -p LV
Let SFA reload the items from the connected controllers every 60 seconds, if new ones are added in future:
eva sfa controller set uc/uc1 reload_interval 60 -y
eva sfa controller set lm/lm1 reload_interval 60 -y
Connecting external applications
There is only one external application - system cron. We won’t connect it via SFA API, but simply by running eva sfa (sfa-cmd) console application.
We provide this example for one reason: you should always connect your external applications to SFA only. Controllers may be changed and, therefore, the setup may be extended: for example, one Logic Manager may be replaced by the three ones installed on the different servers. However, the local SFA will never be changed. All you need is to connect new controllers to it, and EVA item infrastructure will be available again by its usual ID.
The next step it to connect cron for it to run ventilation control macro (edit /etc/crontab or user’s crontab):
0 7 * * * root /path/to/eva sfa macro run control/vi_control -a "0 cron"
0 21 * * * root /path/to/eva sfa macro run control/vi_control -a "1 cron"
As you can see, there is no rocket science here. SCADA Final Aggregator is configured by a few commands and immediately starts collecting the data and events. In turn, it will save you a lot of time by structuring your setup. Now let’s create User interface that will be served by SFA.
Building an interface with EVA JS Framework
- EVA Tutorial parts
- Intro
- Universal Controller configuration
- Logic Manager configuration
- SCADA Final Aggregator configuration
- Building an interface with EVA JS Framework << we are here
So, let us proceed with our configuration. Universal Controller, Logic Manager and SCADA Final Aggregator have already been configured.
The last step is to create the user interface with EVA JS Framework.
Contents
Configuring authentication keys
Note
If you’ve used “easy setup” for the EVA installation, you may skip this step because all controllers are already connected.
Create an SFA API key named operator in etc/sfa_apikeys.ini:
[operator]
key = opsecret
groups = #
pvt = #
hosts_allow = 0.0.0.0/0
and restart SFA:
eva sfa server restart
Configuring users
Create a login for the user to use with operator key:
eva sfa user create john verysecret operator
Framework installation
EVA JS Framework is not included in EVA ICS distribution and should be downloaded manually. Let’s download pre-built JavaScript, full version:
curl https://raw.githubusercontent.com/alttch/eva-js-framework/master/dist/eva.min.js \
-o /opt/eva/ui/eva.min.js
Create a web application
We’ll use EVA JS Framework to write a simple web application to manage our example setup. Create a new index.html file and put it to ui folder:
If the item ids or other information should be hidden from unauthorized users, the additional .js files with such data may be served by SFA PVT or frontend server with additional authentication.
We’ll use jQuery in this example but of course any JavaScript library can be used, as well as Vanilla JS.
<html>
<head>
<title>Plant1 interface</title>
<script src="jquery.min.js"></script>
<script src="eva.min.js"></script>
</head>
<body>
<!-- simple authentication form -->
<div id="loginform">
<form onsubmit="do_login(); return false">
Login:
<input type="text" size="10" name="login" id="i_login" value="" />
<br />
Password:
<input type="password" size="10" name="password"
id="i_password" value="" /><br />
<input type="submit" name="submit" value="GO" />
</form>
</div>
<!-- interface and controls -->
<div id="interface" style="display: none">
<div>Temperature: <span id="temp1"></span></div>
<div>Internal ventilation:
<a onclick="$eva.call('action_toggle', 'ventilation/vi')" href="#">
<span id="vi"></span></a>
</div>
<div>External ventilation:
<a onclick="$eva.call('action_toggle', 'ventilation/ve')" href="#">
<span id="ve"></span></a>
</div>
<div>Hall light:
<a onclick="$eva.call('action_toggle', 'light/lamp1')" href="#">
<span id="lamp1"></span></a>
</div>
<div>Alarm system:
<a onclick="$eva.call('toggle', 'security/alarm_enabled')" href="#">
<span id="alarm_enabled"></span></a>
</div>
<div style="margin-top: 30px">
<a onclick="do_logout()" href="#">logout</a>
</div>
</div>
<script type="text/javascript">
var ed_labels = [ 'DISABLED', 'ENABLED' ];
// function starting EVA JS Framework after the
// authentication form has been submitted
function do_login() {
$('#loginform').hide();
$eva.login = $('#i_login').val();
$eva.password = $('#i_password').val();
$eva.start();
}
// Logout function
function do_logout() {
$eva.stop().then(show_login_form).catch(show_login_form);
}
// function displaying the authentication form
function show_login_form(data) {
$eva.password = '';
$eva.erase_token_cookies();
$('#interface').hide();
$('#i_login').val(eva_sfa_login);
$('#i_password').val('');
$('#loginform').show();
}
// after the page is loaded
$(document).ready(function() {
// after the authentication succeeds the main interface is displayed
$eva.on('login.success', function(data) { $('#interface').show(); });
// if there is a login error
$eva.on('login.failed', function(err) {
// end session and display the authentication form,
// if auth data is incorrect
if (err.code == 2) {
show_login_form();
} else {
// otherwise - repeat the attempts every 2 seconds
// until the server responds
setTimeout(function() { $eva.start() }, 1 * 2000);
}
}
// register the event handlers
$eva.watch(
'sensor:env/temp1', function(state) {$('#temp1').html(state.value)})
$eva.watch(
'unit:ventilation/vi',
function(state) {$('#vi').html(ed_labels[state.status])});
$eva.watch(
'unit:ventilation/ve',
function(state) {$('#ve').html(ed_labels[state.status])});
$eva.watch(
'unit:light/lamp1',
function(state) {$('#lamp1').html(ed_labels[state.status])});
$eva.watch(
'lvar:security/alarm_enabled',
function(state) {$('#alarm_enabled').html(ed_labels[state.value])});
})
</script>
</body>
</html>
Our setup is complete. Interface is available at the following address:
http(s)://<IP_address_SFA:Port>/
The default port for SFA is 8828.
FAQ
Contents
- FAQ
- Is this a “smart home”?
- Is this IoT?
- If the system is free and open, what is your interest?
- Is EVA complex and difficult to learn?
- Is it reliable?
- How about security?
- What programming languages can I use to write scripts and macros?
- What if I have zero experience in programming?
- What automation is all about? What are automation components?
- Is EVA ICS IEC 61131-3 compliant?
- Where is the interface? I want a web interface!
- Why EVA ICS has 3 different APIs?
Is this a “smart home”?
EVA is a universal system used for the construction of both “smart home” and automated control system (ICS) in an industrial enterprise.
In fact, most products positioning themselves as “smart home” are just dumb control panels with a web interface. Moving light switch from the wall to the screen doesn’t make it “smart”. In turn, our system is equipped with a powerful and constantly evolving Logic Manager for automatic decision-making.
Is this IoT?
In a way, yes. As far as IoT is a part of the automation process, we are a part of IoT, in turn. However, from the thousands of components positioning themselves as “IoT”, we choose only those working:
- Reliably
- Safely
- Autonomously
And, most preferably, having an open API to be connected to any system.
The classic situation typical for IoT market involves controlling your device via the Internet with the help of software on the developer servers (aka “clouds”). As you can see it is:
- Unreliable
- Dangerous
- Not autonomous
Moreover, you can’t seriously use it even at home. Our system doesn’t require registration, we don’t need your phone number, email or home address - just download, install and use it. The system works only for you and sends data to no one but you. The code is fully open, so that you can control everything that’s going on. The system doesn’t require Internet access. Everything works fine in the secure local network.
If the system is free and open, what is your interest?
We have been engaged in the automation activities for both private and enterprise sectors for many years. Our clients work with different systems, including previous versions of EVA. The development of EVA 3 is a step towards unification of all configurations that we support and use ourselves.
We decided to distribute the new system completely free of charge, but we provide commercial support for setups where reliability is of critical importance. We are also developing and integrating complex configurations, create additional commercial EVA applications and interfaces for specific systems.
In addition, if:
- you want to become a system integrator and provide commercial support
- you want to distribute our system together with your device
- you want to make us an offer we can’t refuse
you should contact us and we will make a suitable offer to you.
Is EVA complex and difficult to learn?
We try to make our system as simple and user-friendly as possible even for those who have never encountered the process automation.
Is it reliable?
It is reliable enough for home and office setups, as well as for small industrial configurations, but if you use EVA on an enterprise, you should at least understand the system well.
How about security?
Traditionally, automation systems and protocols have been designed as not completely secure. As for reliability, you may agree that it would be a pity if motor or door gets stuck because of incorrect access rights to a folder or an expired SSL certificate. We recommend to have an optimal balance between stability and security and it’s really different for every setup.
What programming languages can I use to write scripts and macros?
As for scripts - you can use any. A script or a program runs as a separate process in the system. It’s only necessary that it reads the input parameters correctly and writes the result in an appropriate format. If you need speed - PERL or DASH are preferred. If speed is not so important, you may use BASH or even PHP.
Logic Manager macros are written in Python, but in most cases, you’ll need to call the internal macro functions only.
Besides, you can create your own applications working through API. The distribution includes API clients for Python and PHP.
What if I have zero experience in programming?
Programming for EVA is only about creating item management scripts. You can find plenty of examples in the documentation.
Additionally you need to program Logic Manager macros for process automation. However, most macros have a very simple structure and call the in-built set of functions.
For example, a macro that runs a pump for watering plants:
# call API action for pump1, controller will be identified automatically
start('farm/pumps/pump1')
# reset the timer for watering
reset('farm/pump1_run')
# message to the log file
info('watering cycle has been started')
# assign "watering" value to the production cycle variable
set('farm/pump1_cycle', 'WATERING')
As you can see, it is not rocket science.
What automation is all about? What are automation components?
The automation components mostly look like relay block, “smart” sockets, “smart” switches - however, there is still some kind of relay inside. Usually, there are 3 ports in the relay: input, two outputs, and two states: open and closed. In the first state, the signal passes through the first output, in the second one - through the second. This is the main principle automation is based on.
Sometimes equipment may include controlled resistors, so that additional parameters (e.g. light dimmer) should be set. In this case, you should send additional value to the controller, e.g. to set a definite percent of capacity.
Our system works not with relay, but with endpoint equipment that is automated. The relay ports are programmed and switched with the help of scripts, which are written once during installation. Thereafter, the system works with the units.
Besides, any automation system has its “eyes” and “ears” for receiving data from the environment and making its own decisions - humidity and temperature sensors, motion sensors etc.
In EVA, all decisions are made either by the user or Logic Manager subsystem.
Is EVA ICS IEC 61131-3 compliant?
EVA Logic Manager is a “cloud” PLC and can’t handle events in real-time. EVA ICS is not a hardware PLC replacement, it brings together equipment of different kind and automates the tasks usually performed by the system operator manually.
However new local nearly real-time PLC and support of ST and FBD languages are planned in the next releases. We are hardly working on it!
Where is the interface? I want a web interface!
Each automated setup needs an interface. EVA has a very powerful SCADA Final Aggregator component, which combines the whole setup itself and provides a flexible EVA JS Framework which allows you to create a modern websocket-powered web interface with a few strings of JavaScript:
$eva.apikey = 'MY_VERY_SECRET_KEY';
$eva.watch'sensor:env/temperature1',
function(state) {
document.getElementById('temp1').innerHTML = state.value;
}
$eva.start();
no rocket science as well.
Why EVA ICS has 3 different APIs?
EVA ICS goal is to allow any possible client perform API calls.
RESTful is a perfect API design architecture when you are 100% sure your client can use it. But there’s still many old equipment/software, which can perform HTTP/GET (plus HTTP/POST, if you’re lucky) requests only.
We have a plans to keep only RESTful and JSON RPC API in EVA ICS v4, but HTTP/GET API compatibility will be kept at least until 2030.
High-load environments
Tuning EVA ICS
To use EVA ICS in high-load environments, remember the following:
- Always turn off debug mode. Debug mode significantly slows down all EVA ICS components.
- Make sure no notifiers are subscribed to the frequently (more than ~10 times per second) updated item states. If you need to synchronize states of such items, reduce remote controller reload intervals instead but set them higher than 1 second.
- Unsubscribe notifiers from INFO log messages and actions
- Replace db_updates = instant in Universal Controller configurations with on_exit or manual.
- If instant state database updates are strongly required, switch to MySQL or PostgreSQL (use option db instead of db_file in controller config).
- If you don’t need action history, set keep_action_history in controllers’ configuration to zero to disable it.
- Turn off logging (comment log_file property in configuration file) and reduce keep_logmem value.
- Increase logging level to warning or error using logging_level config option in [server] section.
- If you use passive updates, set polldelay to the minimal value (0.001 - 0.005 for 1-5ms)
- If HTTP API respond too slow, try increasing value of thread_pool option in [webapi] config section.
- Modbus slave and some utility workers use twisted reactor thread pool. In case the software reacts or performs regular tasks slowly, but system load is still low, try increasing value of reactor_thread_pool option in [server] section.
Hardware
Thanks to EVA ICS architecture and optimization for modern multi-core CPUs, the platform can provide good results even on a microcomputers. System components and CLI tools may require more time to launch on architectures different than Intel x86_64, but the regular performance should not be affected even on an embedded ARM-based systems.
According to tests, EVA ICS can show bad performance (slow startup/shutdown) on industrial and micro computers if they have:
- small amount of RAM (minimum 512 MB is recommended)
- slow SSD drive or SD card.
We strongly recommend using at least UHS-I SD cards which can show a speed up to 100 MB/s.
Benchmarks
Benchmark tests for Universal Controller can be performed with tests/benchmark-uc-crt tool. Benchmark results may be different on a systems with different background load, so please stop all unnecessary processes before starting a test.
The primary parameter for UC which is benign benchmarked is a time, required for the controller to:
- obtain item state from driver
- perform a simple in-core event handling (convert item value to float and then compare with a float number) with self thread-locking
- get action request from event handler and execute it using another driver
The time between a moment when the first driver gets new item value and a moment when the second driver is ready to call equipment action is named Core Reaction Time (CRT).
The benchmark tool for Universal Controller turns on internal controller benchmark, performs 1000 CRT tests with 30ms delays on a single sensor/unit pair and displays the average CRT value in milliseconds.
The benchmark is performed on virtual drivers, so the actual system reaction time may be higher than CRT, depending on the equipment connected.
Warning
It’s not recommended to perform a real benchmarking tests on SOHO and light industry relays due to their limited lifetime (~100-200k switches)
Below are benchmark results on a test systems (lower CRT is better):
| System | CPU | Cores | EVA ICS | CRT, ms |
|---|---|---|---|---|
| VMWare ESXi 5.5 | Intel Xeon E5630 2.53GHz | 1 | 3.1.1 2018101701 | 4.5 |
| VMWare ESXi 5.5 | Intel Xeon E5630 2.53GHz | 4 | 3.1.1 2018101701 | 3 |
| VMWare ESXi 5.5 | Intel Xeon D-1528 1.90GHz | 1 | 3.1.1 2018101701 | 5 |
| VMWare ESXi 5.5 | Intel Xeon D-1528 1.90GHz | 4 | 3.1.1 2018101701 | 3.5 |
| Supermicro X9SXX | Intel Xeon E3-1230 V2 3.30GHz | 8 | 3.1.1 2018101701 | 4 |
| Supermicro E100 | Intel Atom E3940 1.60GHz | 4 | 3.1.1 2018101701 | 8.5 |
| Raspberry Pi 1A | ARMv6 rev 7 v6l | 1 | 3.1.1 2018101701 | 110 |
| Raspberry Pi 2B | ARMv7 rev 5 v7l | 4 | 3.1.1 2018101701 | 22.5 |
| Raspberry Pi 3B+ | ARMv7 rev 4 v7l | 4 | 3.1.1 2018101701 | 21 |
| UniPi Axon S115 | ARMv8 Cortex-A53 | 4 | 3.1.1 2018101701 | 27 |
According to tests, EVA ICS 3.2 is about 15% faster than 3.1.1
Universal Controller
EVA Universal Controller (UC) is a control and monitoring subsystem.
It should be installed if you actually want to control something. UC is controlled via UC EI web interface or eva uc (uc-cmd) console application. Additionally, it can be integrated into other subsystems and third-party programs using UC API.
You may use Universal Controller independently or integrate it with other EVA subsystems.
Units receive control actions, the controller forms them into queues and executes them using external scripts. If necessary, it terminates the current script and keeps the command history.
Additionally, Universal Controller collects data from the connected items using active and passive status updates.
Universal Controller can control equipment directly and/or act as a gateway for other local controllers.
Item status and values are stored in the local database. Other subsystems or third-party programs can read them using UC API.
Units and sensors are controlled via UC EI interface, configured via UC API. States are controlled and updated using drivers and item scripts.
All changes of item status, current control commands, and progress logs are sent to the notification system.
UC POLL DELAY
EVA is a real-time system. Being one of its essential components, UC also follows this rule. The value of poll delay is set in configuration in seconds (milliseconds using dot), e.g. 0.01.
The value of POLL DELAY means that all timeouts and events in the system should fulfill their functions for not more than TIME_SET + POLL DELAY.
Reducing POLL DELAY will increase the CPU load on the server; in turn, if increased, the UC reaction time will be longer. Recommended values: 0.1 for home and office, 0.01 and less - for industrial applications.
The optimum value of POLL DELAY for UC can be set via eva sfa, or by manually calling UC API functions and comparing reaction/execution time of the commands.
The minimum value of POLL DELAY is 0.001 (1 millisecond).
etc/uc.ini configuration file
uc.ini - primary configuration file of UC server
[server]
; system name (default - hostname)
; name = eva-uc1
; system polldelay
polldelay = 0.01
; pid file (default var/uc.pid)
pid_file = var/uc.pid
; log file
log_file = log/uc.log
; db updates - instant, manual or on_exit
db_update = instant
; db file, default runtime/db/uc.db
db_file = runtime/db/uc.db
; use MySQL instead of SQLite
;db = mysql+pymysql://user:password@localhost/dbname
; user db file, default = db_file
; one user db may be used by multiple controllers at once
;userdb_file = runtime/db/users.db
; use MySQL instead of SQLite
;userdb = mysql+pymysql://user:password@localhost/dbname
; launch external script/program when user is created/got new
; password/destroyed. additional arguments:
; 1) create | set_password | destroy
; 2) user
; 3) password (for create and set_password operations)
;user_hook = /opt/eva/xbin/htpasswd.sh /opt/eva/etc/htpasswd
; keep action history in seconds
keep_action_history = 86400
; action cleaner interval, in seconds
action_cleaner_interval = 60
; keep memory log in seconds
keep_logmem = 86400
; notify state on start
notify_on_start = yes
; debug mode
debug = no
; logging level, info, warning, error or critical
;logging_level = info
; create crash dump on critical errors
dump_on_critical = yes
; stop server on critical errors (will be restarted via safe-run)
; always - stop on all critical errors
; core - core errors only (ignore driver critical errors)
; no - don't stop
stop_on_critical = always
; default timeout
timeout = 5
; layout (simple or enterprise)
layout = enterprise
; reactor thread pool size (used by Modbus slave and some utility workers)
;reactor_thread_pool = 15
; exec commands before/after config/db save,
; e.g. mount -o remount,rw / (then back to ro)
;exec_before_save =
;
;exec_after_save =
; default mqtt notifier for updates for new items
;mqtt_update_default = eva_1:2
[sysapi]
; enable remote file management functions
file_management = yes
; allow entering setup mode
setup_mode = yes
[webapi]
; web api listen on IP/port
listen = 0.0.0.0:8812
;ssl_listen = 0.0.0.0:8813
;ssl_module = builtin
;ssl_cert = test.crt
;ssl_key = test.key
;ssl_chain = test.pam
; session timeout, set to non-zero to enable API session tokens
session_timeout = 3600
; session tokens will expire even if active requests are received
;session_no_prolong = yes
; server thread pool
;thread_pool = 15
; uncomment to disable UC EI
;ei_enabled = no
; uncomment to use frontend X-Real-IP header to get client real IP address
;x_real_ip = yes
[snmptrap]
; snmp trap handler, default community is eva
listen = 127.0.0.1:162
community = eva
; hosts, allowed to send snmp traps
hosts_allow = 127.0.0.0/8
[udpapi]
; udp api
listen = 127.0.0.1:8881
; hosts, allowed to send UDP commands
hosts_allow = 127.0.0.0/8
hosts_allow_encrypted = 0.0.0.0/0
[modbus]
; modbus slave configuration
; first number indicates modbus address (hex or decimal)
; multiple values can be specified
; modbus slave memory space size: 10000 registers (starting from 0) for each
; type (holding, input, coils, discrete inputs)
;tcp0 = 0x01,0.0.0.0:502
;udp0 = 0x01,0.0.0.0:502
; framer for serial: rtu, ascii or binary
;serial0 = 0x01,rtu:/dev/ttyS0:9600:8:N:1
;serial1 = 0x05,rtu:/dev/ttyS1:9600:8:N:1
runtime/uc_cvars.json variables file
uc_cvars.json - file containing user variables passed to all commands and item scripts within the system environment.
The file contains a JSON dict:
{
"VAR1": "value1",
"VAR2": "value2"
}
Variables can be changed while the server is running via SYS API as well as eva uc cvar_get and cvar_set commands.
For example, let’s create a variable:
eva uc cvar set RELAY1_CMD "snmpset -v1 -c private 192.168.1.208 .1.3.6.1.4.1.19865.1.2."
After UC is started, it will become available for system environment, and unit management script on the port 2 of the given relay will be the following:
#!/bin/sh
${RELAY1_CMD}.1.2.0 i $2
It’s possible to assign different values for the variables used for different object groups with the same names, e.g. group1/VAR1, group2/VAR1 etc. In this case the variable will be available only for the specified group.
etc/uc_apikeys.ini API keys file
API access keys are stored into etc/uc_apikeys.ini file. At least one full access key named masterkey should be present for proper functioning. Important: with master key and API anyone can receive full access to the system similar to root user (or the user UC is run under), that is why it is recommended to use this key only in supervisory networks or even restrict its use to local host only.
[masterkey]
; the default master key is eva, change it!
key = eva
master = yes
hosts_allow = 127.0.0.1
;[key1]
;key = key1secret
;groups = group1/#, group2, group3/+/somegroup
;hosts_allow = 0.0.0.0/0
;[key2]
;key = key2secret
;items = unit1, unit2
;sysfunc = yes
;allow = cmd, lock, device
;hosts_allow = 0.0.0.0/0
; key will be assigned to requests from these hosts if no key provided
;hosts_assign = 192.168.1.1
;[lm]
;key = lmsecret
;groups = #
;sysfunc = yes
;allow = cmd
;hosts_allow = 127.0.0.1, 192.168.0.0/16
;[sfa]
;key = sfasecret
;groups = #
;hosts_allow = 127.0.0.1, 192.168.0.0/16
Action queues
All the unit control actions are queued right after they’re created. Item status update actions are not queued and just run in accordance with the set intervals.
Before execution, the control action is placed in two queues:
- global queue for all actions
- certain unit queue
All actions have their “priority” set when they are generated. The default priority is 100. The lower means the higher priority of queued action execution.
Queued action can have the following status:
- created action has just been created and has not been queued yet
- pending the action is placed in the global queue. The previous action status, as well as this one, are rarely found because UC API waits for the command to be placed in the queue of a certain unit and then returns the result
- queued the action has already passed the global queue and is now waiting to be executed in the queue of a certain unit
- refused unit rejected the action execution because of the item configuration value action_enabled=False
- dead API failed to wait until the action is placed to the queue of a certain unit and, therefore, marked it as “dead”. Virtually, such status clearly indicates that server is seriously overloaded
- canceled the command is canceled either from the outside or due to either unit already running the other action (in case action_queue=0 and queue is disabled) or the unit has got new action to execute and action_queue=2 (cancel and terminate the pending actions after getting a new one)
- ignored the unit rejected the action execution, because its status/value are the same as requested to be changed to, and action_always_exec=False
- running the action is being executed
- failed the controller failed to execute the command
- terminated the controller terminated the action execution due to timeout or by the external request
- completed the action finished successfully
Startup and shutdown
To manage UC controller server, use:
- eva uc server start start UC server
- eva uc server stop stop UC server
- eva uc server restart restart UC server
- eva uc server reload restart controller only (without watchdogs)
The controller startup/shutdown is also performed by ./sbin/eva-control which is configured during the system setup.
Logic Manager
EVA Logic Manager (LM PLC) - is a programmable logic controller.
This subsystem is designed to automatically manage hardware and decision-making process when the metrics are changed. Unlike standard PL controllers, LM PLC is a network-based controller, its mission is to control equipment in local networks and work as cloud controller via the Internet.
LM PLC operations can be event-based, cycle-based, and called manually by used.
LM PLC is customized and controlled via LM EI web interface or eva lm (lm-cmd) console application. It can also be integrated into other subsystems and third-party programs using LM API.
Additionally, you can use console applications for better control of the decision-making rules.
LM PLC additionally introduces one more control and monitoring item: logic variable (lvar). Logic variables are used to save and exchange system status data as well as function as flags and timers for organizing production cycles.
Any change in the status of units, sensors or logic variables is analyzed by the decision-making matrix of a certain LM controller. In case the rule conditions match, the controller calls the indicated macro that performs the specified actions.
Logic variables statuses are stored in the local database and can be accessed via LM API by other subsystems or third-party programs. Status changes are sent via notification system. To let LM PLC operate with the items of UCs in real time, it should be connected to MQTT server.
Since LM PLC is a part of EVA platform, its operating principles, settings, and configuration files generally match the other components.
etc/lm.ini configuration file
lm.ini - primary configuration file of LM PLC
[server]
; system name (default - hostname)
; name = eva3-lm1
; system polldelay
polldelay = 0.01
; pid file (default var/lm.pid)
pid_file = var/lm.pid
; log file
log_file = log/lm.log
; db updates - instant, manual or on_exit
db_update = instant
; db file, default runtime/db/lm.db
db_file = runtime/db/lm.db
; use MySQL instead of SQLite
;db = mysql+pymysql://user:password@localhost/dbname
; user db file, default = db_file
; one user db may be used by multiple controllers at once
;userdb_file = runtime/db/users.db
; use MySQL instead of SQLite
;userdb = mysql+pymysql://user:password@localhost/dbname
; launch external script/program when user is created/got new
; password/destroyed. additional arguments:
; 1) create | set_password | destroy
; 2) user
; 3) password (for create and set_password operations)
;user_hook = /opt/eva/xbin/htpasswd.sh /opt/eva/etc/htpasswd
; keep action history in seconds
keep_action_history = 86400
; action cleaner interval, in seconds
action_cleaner_interval = 60
; keep memory log in seconds
keep_logmem = 86400
; notify state on start
notify_on_start = yes
; debug mode
debug = no
; logging level, info, warning, error or critical
;logging_level = info
; create crash dump on critical errors
dump_on_critical = yes
; stop server on critical errors (will be restarted via safe-run)
stop_on_critical = yes
; default timeout
timeout = 5
; layout (simple or enterprise)
layout = enterprise
; reactor thread pool size (used by some utility workers)
;reactor_thread_pool = 15
; exec commands before/after config/db save,
; e.g. mount -o remount,rw / (then back to ro)
;exec_before_save =
;
;exec_after_save =
; default mqtt notifier for updates for new items
;mqtt_update_default = eva_1:2
[sysapi]
; enable remote file management functions
file_management = yes
; allow entering setup mode
setup_mode = yes
[webapi]
; web api listen on IP/port
listen = 0.0.0.0:8817
;ssl_listen = 0.0.0.0:8818
;ssl_module = builtin
;ssl_cert = test.crt
;ssl_key = test.key
;ssl_chain = test.pam
; session timeout, set to non-zero to enable API session tokens
session_timeout = 3600
; session tokens will expire even if active requests are received
;session_no_prolong = yes
; server thread pool
;thread_pool = 15
; uncomment to disable LM EI
;ei_enabled = no
; uncomment to use frontend X-Real-IP header to get client real IP address
;x_real_ip = yes
[mailer]
; mailer for mail() macro function
smtp = localhost
from = eva@eva3-lm1
default_rcp = admin@localhost, root@localhost
runtime/lm_cvars.json variables file
lm_cvars.json - file containing user variables passed to all logic control macros.
The file contains a JSON dict:
{
"VAR1": "value1",
"VAR2": "value2"
}
Variables can be changed while the server is running via SYS API as well as eva lm cvar get and cvar set commands.
etc/lm_apikeys.ini API keys file
API access keys are stored into etc/lm_apikeys.ini file. At least one full access key named masterkey should be present for proper functioning. Important: with master key and API anyone can receive full access to the system similar to root user (or the user LM is run under), that is why it is recommended to use this key only in supervisory networks or even restrict its usage to local host only.
[masterkey]
; the default master key is eva, change it!
key = eva
master = yes
hosts_allow = 127.0.0.1
;[key1]
;key = key1secret
;groups = group1/#, group2, group3/+/somegroup
;hosts_allow = 0.0.0.0/0
;[key2]
;key = key2secret
;items = macro1, lvar1, lvar2
;sysfunc = yes
;allow = cmd
;hosts_allow = 0.0.0.0/0
; key will be assigned to requests from these hosts if no key provided
;hosts_assign = 192.168.1.1
;[sfa]
;key = sfasecret
;groups = #
;hosts_allow = 127.0.0.1, 192.168.0.0/16
Connecting UC controllers
Logic macros and decision-making matrix work only with the items known to the controller, so Logic Manager loads information about units and sensors from the connected Universal Controllers.
Prior to UC connection, it is necessary to connect LM PLC to MQTT server, where other controllers will send the events. Logic Manager reads the list of items and their initial status from the connected controllers; further status monitoring is performed via MQTT. In case MQTT server is inaccessible or has data exchange problems, states of the items are updated on every remote controller reload (reload_interval prop).
To connect UC controllers you should use eva lm console command or LM API append_controller function.
When connecting, it is necessary to indicate minimum URI of the connected controller and API KEY functioning either as a master key or the key with access to certain items. If Logic Manager and UC keys are the same, the key can be set as $key (\$key in the command line). In this case, LM will use the local key of its own configuration.
eva lm controller append http://localhost:8812 -a secretkey -y
Configurations of connected controllers are stored in the following folder: runtime/lm_remote_uc.d/
Logic Manager automatically loads the connected controller data (its ID) and saves configuration to runtime/lm_remote_uc.d/ID.json file.
Items from remote controllers are loaded at the LM PLC start and then refreshed with reload_interval frequency set individually for each connected controller. If LM PLC fails to get the item list during loading, it will use the existing one.
To control the list of the received items you can use eva lm or LM API function list_remote:
eva lm remote -p unit
eva lm remote -p sensor
All connected controllers have the following properties that can be changed while LM PLC is running:
- description optional description of the controller
- key API key used to access the connected controller
- mqtt_update MQTT notifier through which items update their status
- reload_interval interval (seconds) to reload the item list from the server, 0 - load the list only at the start
- ssl_verify either verify or not the SSL certificate validity when working through https://. May be True (verify) or False (not verify) The certificate is verified by default.
- timeout request timeout (seconds)
- uri API URI of the connected controller (proto://host:port, without /uc-api/)
Parameters are displayed with eva lm command or Logic Manager list_controller_props function, modified with set_controller_prop. Function list_controllers displays the list of all connected controllers.
To remove the connected controller use remove_controller function.
When managing the connected controllers, ID can be either the controller ID only or the full ID in the following format: controller_type/ID (i.e. uc/controller1).
Macro execution queues
Prior to execution, the macros are put into global queue. The macros are executed progressively without waiting for the completion of the previous macro. The queue is used for reporting only and reserved for some internal functions. If a macro is required to block execution of the other ones, one should use lock and unlock macro functions operating similarly to SYS API locking.
The status of the macro in queue is similar to the status of the Universal Controller actions.
Startup and shutdown
To manage LM controller server, use:
- eva lm server start start LM server
- eva lm server stop stop LM server
- eva lm server restart restart LM server
- eva lm server reload restart controller only (without watchdogs)
The controller startup/shutdown is also performed by ./sbin/eva-control which is configured during the system setup.
SCADA Final Aggregator
SCADA Final Aggregator (SFA) is a subsystem usually installed directly in the host wherein the user interface or third-party applications are installed.
It aggregates all the control and monitoring items, logic macros and decision rules from all connected UC and LM PLC controllers into one place. As a result, the final interface or application doesn’t need to know on which controller the item is present, it does all the function calls directly to SFA. Ids of the items should be always specified in oid form (type:group/id) and be unique in the whole installation.
Example of the controller aggregation with the use of two SFA servers
SFA is set up and controlled with eva sfa console application and SFA API. The API doesn’t have a user interface by default, it’s developed specifically for certain installation certain installation using SFA Templates (server-side part) and EVA JS Framework (client-side part).
All changes of item status, actions, and logs are sent to the notification system. In addition, SFA can function as the notification aggregator e. g. by transferring MQTT messages to other application via HTTP or redirecting them to other MQTT servers. SFA usually has several or all available controllers connected. At least one MQTT server should be installed in the setup to let it work in real time.
Since SFA is a part of EVA platform, its operating principles, settings, and configuration files generally match the other components.
etc/sfa.ini configuration file
sfa.ini - primary configuration file of SFA
[server]
; system name (default - hostname)
; name = eva3-sfa1
; system polldelay
polldelay = 0.01
; pid file (default var/sfa.pid)
pid_file = var/sfa.pid
; log file
log_file = log/sfa.log
; db updates - instant, manual or on_exit
db_update = instant
; db file, default runtime/db/sfa.db
db_file = runtime/db/sfa.db
; use MySQL instead of SQLite
;db = mysql+pymysql://user:password@localhost/dbname
; user db file, default = db_file
; one user db may be used by multiple controllers at once
;userdb_file = runtime/db/users.db
; use MySQL instead of SQLite
;userdb = mysql+pymysql://user:password@localhost/dbname
; keep action history in seconds
; launch external script/program when user is created/got new
; password/destroyed. additional arguments:
; 1) create | set_password | destroy
; 2) user
; 3) password (for create and set_password operations)
;user_hook = /opt/eva/xbin/htpasswd.sh /opt/eva/etc/htpasswd
; keep action history in seconds
keep_action_history = 86400
; action cleaner interval, in seconds
action_cleaner_interval = 60
; keep memory log in seconds
keep_logmem = 86400
; debug mode
debug = no
; logging level, info, warning, error or critical
;logging_level = info
; create crash dump on critical errors
dump_on_critical = yes
; stop server on critical errors (will be restarted via safe-run)
stop_on_critical = yes
; default timeout
timeout = 5
; reactor thread pool size (used by some utility workers)
;reactor_thread_pool = 15
; exec commands before/after config/db save,
; e.g. mount -o remount,rw / (then back to ro)
;exec_before_save =
;
;exec_after_save =
; default mqtt notifier for updates for new items
;mqtt_update_default = eva_1:2
[sysapi]
; enable remote file management functions
;file_management = yes
; allow entering setup mode
setup_mode = yes
[webapi]
; web api listen on IP/port
listen = 0.0.0.0:8828
;ssl_listen = 0.0.0.0:8829
;ssl_module = builtin
;ssl_cert = test.crt
;ssl_key = test.key
;ssl_chain = test.pam
; session timeout, set to non-zero to enable API session tokens
; note: SFA Framework will not work without sessions
session_timeout = 3600
; session tokens will expire even if active requests are received
;session_no_prolong = yes
; server thread pool
;thread_pool = 15
; uncomment to use frontend X-Real-IP header to get client real IP address
;x_real_ip = yes
[cloud]
; enable cloud manager services
;cloud_manager = yes
runtime/sfa_cvars.json variables file
sfa_cvars.json - file containing user variables. All SFA user variables are directly available in SFA Templates and EVA JS Framework after login with any valid user or API key.
The file contains a JSON dict:
{
"VAR1": "value1",
"VAR2": "value2"
}
Variables can be changed while the server is running via SYS API as well as eva sfa cvar get and cvar set commands.
etc/sfa_apikeys.ini API keys file
API access keys are stored into etc/sfa_apikeys.ini file. At least one full access key named masterkey should be present for proper functioning. Important: with master key and API anyone can receive the full access to the system similar to root user (or the user SFA is run under), that is why it is recommended to use this key only in supervisory networks or even restrict its use to local host only.
[masterkey]
; the default master key is eva, change it!
key = eva
master = yes
hosts_allow = 127.0.0.1
;[key1]
;key = key1secret
;groups = group1/#, group2, group3/+/somegroup
;pvt = #
;rpvt = 127.0.0.1/#
;hosts_allow = 0.0.0.0/0
; key will be assigned to requests from these hosts if no key provided
;hosts_assign = 192.168.1.1
;[key2]
;key = key2secret
;items = macro1, lvar1, lvar2
;sysfunc = yes
;allow = cmd
;pvt = dir1/#, file1, dir2/file2, dir3/+/content.js
;rpvt = 127.0.0.1:8080/file1.png 127.0.0.1:8080/img/#
;hosts_allow = 0.0.0.0/0
Connecting UC and LM PLC controllers
SFA works only with the items known to the controller. Prior to connecting UC and LM PLC remote controllers, it is necessary to connect SFA to MQTT server (via its notification system), to which other controllers will send the events. SFA reads the list of items, macros, rules and the initial item status from the connected controllers; further status updates are performed via MQTT.
For timers to be displayed correctly in the user interface, it is important to maximally synchronize the system time between LM PLC and SFA, if LM PLC controllers are set up on the remote servers.
To connect the controllers you should use eva sfa (sfa-cmd) console command or SFA API append_controller function.
When connecting, it is necessary to indicate minimum URI of the connected controller and API KEY functioning either as a master key or the key with access to certain items. If Logic Manager and UC keys are the same, the key can be set as $key (\$key in the command line). In this case, LM will use the local key of its own configuration.
eva sfa append_controller -u http://localhost:8812 -a secretkey -y
eva sfa append_controller -u http://localhost:8817 -a secretkey -y
You may specify a controller type with -g argument (-g uc or -g lm). If the group is not specified, SFA tries to automatically detect the remote controller type.
Configurations of the connected controllers are stored in the folder runtime/sfa_remote_uc.d/ for UC and runtime/sfa_remote_lm.d/ for LM PLC.
SFA automatically loads the connected controller data (its id) and saves the configuration to runtime/sfa_remote_<type>.d/<ID>.json.
Items from remote controllers are loaded at the SFA start and then refreshed with reload_interval frequency set individually for each connected controller. If SFA fails to get the item list during loading, it will use the existing one.
To control the list of the received items you can use eva sfa or SFA API function list_remote:
eva sfa remote -p unit
eva sfa remote -p sensor
efa sfa remote -p lvar
The available logic macros are listed by the command
eva sfa macro list
Note
Macros from system group and its subgroups are not loaded to SFA
All connected controllers have the following properties that can be changed while SFA is running:
- description optional description of the controller
- key API key used to access the connected controller
- mqtt_update MQTT notifier through which items update their status
- reload_interval interval (seconds) to reload the item list from the server, 0 - load the list only at the start
- ssl_verify either verify or not the SSL certificate validity when working through https://. May be True (verify) or False (not verify) The certificate is verified by default.
- timeout request timeout (seconds)
- uri API URI of the connected controller (proto://host:port, without /uc-api/ or /lm-api/)
Parameters are displayed with eva sfa command or SCADA Final Aggregator list_controller_props function, modified with set_controller_prop. Function list_controllers displays the list of all connected controllers.
To remove the connected controller use remove_controller function.
When managing the connected controllers, ID should be always provided in the full format: controller_type/ID (i.e. uc/controller1).
Interface
SFA interface is always specifically designed for a certain installation using SFA Templates, EVA JS Framework and SFA PVT. Interface files are stored in ui folder, interface is available at http(s)://<IP_address_SFA:Port>/ (redirects to /ui/) or http(s)://<IP_address_SFA:Port>/ui/.
Startup and shutdown
To manage SFA controller server, use:
- eva sfa server start start SFA server
- eva sfa server stop stop SFA server
- eva sfa server restart restart SFA server
- eva sfa server reload restart controller only (without watchdogs)
The controller startup/shutdown is also performed by ./sbin/eva-control which is configured during the system setup.
Control and monitoring items
An item in EVA means any object which can be controlled or monitored. Universal Controller has 2 native item types: unit and sensor, plus multi-updates, which may contain multiple items at once.
Logic Manager has one native item type lvar (logic variable), additionally it loads remote units and sensors from connected UCs. SCADA Final Aggregator has no native item types and loads everything from the connected remote controllers.
The configurations of items are stored in runtime folder, from where the controllers loads .json files. Each item has multiple parameters which may be predefined or customized. All customized parameters can be displayed with the help of API list_props or EVA console tools In case the configuration file settings are changed manually or by 3rd party software, controller should be restarted to reload the configurations.
Contents
Common item parameters
- id item ID, e.g. ‘lamp1’. When using simple layout, must be unique within one controller, even if items are in different groups. This creates some complications when designing the whole installation architecture but allows to keep EVA configuration and item scripts organized in a simple way and makes system administration and support much easier.
- group item group, i.e. ‘hall/lamps’. Assigned at the time of item creation, the group can’t be changed later to avoid synchronization problems.
- full_id full item id (i.e. ‘hall/lamps/lamp1’), read-only. Must be unique within one controller despite of layout used.
- oid object id, unique within the whole installation, same as full_id, but also contains the item type: ‘unit:hall/lamps/lamp1’, read-only
- description item description
Note
All EVA functions, commands and parameters can accept oid as the item identifier.
Item layout
EVA ICS allows to use two types of item layouts: simple and enterprise. if the system is not being used yet and there are no items created, layout can be set in Universal Controller and Logic Manager configuration files (option within [server]: layout=<simple|enterprise>). Otherwise you should use sbin/layout-converter tool to convert simple layout to enterprise. Inverse conversion is not possible.
Benefits of simple layout:
- Good to use in simple installations or in the installations where each component has no similar items. Each item should have its own unique ID, despite that items are located in different groups.
- When doing controller maintenance tasks, you can address each item by its ID instead of full ID or oid.
- Item configuration files are named as <ID>.json and can be easily located.
Benefit of enterprise layout: different items in different groups can have the same IDs. Ideal for setups where multiple similar components are managed by one controller.
In general, simple layout should be used only for testing and simple temporary setups. For usage in production environment, enterprise layout is always recommended.
Unit
A unit is a physical item, a device that we control. A unit is not a relay port, a dimmer or a controlled resistor. This is an object, for example: an electric lamp chain, a door, ventilation, a window, a pump or a boiler.
The unit can be controlled with one relay (e.g. a lamp chain: we control the whole chain by turning on/off the relay port) or with several ones (controlling e.g. a garage door often requires two relays: the first one starts the motor, the second one chooses the direction of movement). However, a door is one unit with “open” or “closed” statuses.
All units are connected to Universal Controller subsystems, which control them and form the single “unit” with one or several relays/programmable switches using control scripts. One Universal Controller can work with multiple units, but one unit should be connected to only one Universal Controller in order to avoid conflicts. Nevertheless, for reliability, one unit can be connected to several controllers, if its state is correctly synchronized via MQTT.
Each unit has its unique ID, for example “lamp1”. ID can include numbers, uppercase and lowercase Latin characters and some special characters like minus (-) or dot (.).
Unit parameters are set via configuration.
Status of the unit state
Status of the unit state is always an integer (a positive number or 0), and is by default 0 - unit is “off” (inactive) and 1 - “on” (active).
A unit can have other statuses: for example, a dimmer can include status 2 - enabled at 10% of the capacity, 3 - enabled at 50% of the capacity, window may be fully open or 50%. In the item configuration, you may assign a label to each status for enhancing its usability in interfaces.
Status -1 indicates that unit has an error status. It is set from the outside or by the system itself if the unit wasn’t updated for more than “expires” (value from item config) seconds.
Value of the unit state
Sometimes it’s not necessary to create multiple new statuses for the unit. In such cases, the unit also has a “value” parameter (which can include both numbers and letters). For instance, a motor can be controlled by two unit statuses - 0 and 1, i.e. turned on/off, but Its speed is set by value. You can also use value to control e.g. dimmers.
EVA does not use unit value for internal control and monitoring logic (except in your custom macros), that is why you can set it to any value or several values separating them with special characters for further processing.
Units in EVA hive
All units have OIDs like unit:group/unit_id e.g. unit:light/room1/lamp1
For synchronization via MQTT, the following subjects are used for units
- [space/]unit/<group>/<unit_id>/status unit status, integer
- [space/]unit/<group>/<unit_id>/value unit value
- [space/]unit/<group>/<unit_id>/nstatus new unit status (different from status if action is started), integer
- [space/]unit/<group>/<unit_id>/nvalue new unit value
- [space/]unit/<group>/<unit_id>/action_enabled are actions enabled for the unit or not (boolean, True/False)
Unit parameters
- expires integer value, time (seconds) after which the item state is considered “expired”. If the item state was not updated during this period, the state automatically is set to -1 (error), value is deleted (set to null). If ‘expires’ param is set to 0, this feature is disabled. The minimum expiration step is 0.1 sec.
- mqtt_update = “notifier:qos” if set, the item may receive active state updates through notification from the specified MQTT server. Example: “eva_1:2”.
- snmp_trap if set, the item may receive active state updates via SNMP traps.
- update_exec a script for passive update of the item state, “xc/uc/ITEMID_update” by default.
- update_interval integer value, time (seconds) interval between the calls for passive update of the item. Set 0 to disable passive updates. Minimum step is 0.1 sec.
- update_delay integer value, delay (in seconds) before the next call of the passive update, may be used to avoid multiple update scripts of different items run simultaneously.
- update_timeout integer, value, time (seconds) in which the script of the passive update should finish its work or it will be terminated.
- action_allow_termination boolean, allow currect running action termination by external request.
- action_always_exec boolean, always execute the actions, even if the intended status is similar to the current one
- action_enabled boolean, allow or deny new actions queue/execution
- action_exec a script which performs the action, “xc/uc/ITEMID” by default.
- action_queue={0|1|2}
- 0 action queue is disabled, if the action is running, new actions are not accepted
- 1 action queue is enabled, all new actions are put in queue and executed in a normal way
- 2 queue is disabled, new action terminates the current running one and then is executed
- action_timeout integer, value, time (seconds) in which the script of the action should finish its work or it will be terminated.
- auto_off integer, the simple automation parameter: the command to turn the unit off (call an action to set status = 0) will be executed after the indicated period of time (in seconds) after the last action performed for this unit. Set 0 to disable this feature. Minimum step is 0.1 sec.
- location you may specify units’ physical location, as GPS coordinates or in custom format. To specify GPS coordinates, set the parameter to value longitude:latitude or longitude:latitude:altitude. If you choose to set location as GPS or some other coords, full unit state is appended with virtual parameters loc_x, loc_y (and if altitude is specified - loc_z). These virtual parameters are parsed automatically from location and can be used later e.g. to filter units by location or to put units on geographical map.
- mqtt_control = “notifier:qos” item gets actions through notifications from a specified MQTT server, for example “eva_1:2”, actions should be sent to path/to/unit/control (e.g. unit/hall/lamps/lamp1/control) in a form of text messages “status [value] [priority]”. If you want to skip value, but keep priority, set it to null, i.e. “status 0 null 50”.
- modbus_status, modbus_value update item state from :ref`Modbus slave<modbus_slave>` memory space.
- status_labels “labels” used to display the unit statuses by the interfaces. Labels may be changed via UC API or eva uc, in the following way: status:number = label, e.g. “status:0” = “stop”. By default the unit has labels “status:0” = “OFF”, “status:1” = “ON”. Status labels can be used as status param to execute unit actions, in this case controllers check the status match to the specified label (case insensitive).
- term_kill_interval integer, difference (in seconds) between stopping and forcible stopping the action or update script. Tip: sometimes it is useful to catch SIGTERM in the script to exit it gracefully. Cannot exceed the value of timeout** 2, where timeout** default timeout, set in a controller config.
- update_exec_after_action boolean, start passive update immediately after the action is completed (to ensure the unit state has been changed correctly)
- update_if_action boolean, allow or deny passive updates while the action is being executed
- update_state_after_action boolean, if action is completed successfully, the controller assumes that its actual unit state has been changed correctly and sets it without calling/waiting for the state update.
- maintenance_duration integer, if greater than zero, item can enter maintenance mode on the specified amount of seconds. During maintenance mode all item updates are ignored, however actions still can be executed. If expires property is also set, item state expire after maintenance_end + expires seconds.
Sensor
The sensor value is the parameter measured by the sensor: temperature, humidity, pressure etc.
In terms of automation the difference between sensor item and unit item is obvious: we change the unit state by ourselves and monitor it only for the sake of checking the control operations, while the sensor state is changed by the environment.
Regarding the system itself, unit and sensor are similar items: both have status and value, the item status is monitored actively (by UC API, MQTT message, SNMP traps) or passively (by calling the external script).
The sensor can have 3 statuses:
- 1 sensor is working and collecting data
- 0 sensor is disabled, the value updates are ignored (this status may be set via API or by the user)
- -1 sensor error (“expires” timer went off, the status was set because the connection with a physical sensor got lost during passive or active update etc), when the sensor is in this status, its value is not sent via notification system to let other components work with the last valid data.
Note
The sensor error state is automatically cleared if new value data arrives.
Important: the sensor error may be set even if the sensor is disabled. It means that the disabled sensor may be switched to “error” and then to “work” mode by the system itself. Why it works that way? According to the logic of the system, the sensor error is an emergency situation that should affect its status even if it is disabled and requires an immediate attention of the user.
Sensors (and sometimes units) can be placed on the same detector, controller or bus queried by a single command. EVA can use multi-updates in order to update several items at once.
Since the system does not control, but only monitors the sensor, it can be easily connected to several Universal Controllers at once if the equipment allows making parallel queries of the state or sending active updates to several addresses at once.
Note
The sensor doesn’t set its status to ‘-1’ on expires if its status is 0 (disabled)
Sensors in EVA hive
All sensors have OIDs like sensor:group/sensor_id e.g. sensor:temp/t1
For synchronization via MQTT, the following subjects are used for units
- [space/]sensor/<group>/<sensor_id>/status sensor status, integer
- [space/]sensor/<group>/<sensor_id>/value sensor value
Sensor parameters
Sensors have the same parameters as units, except they don’t have action_*, auto_off, mqtt_control, modbus_status and status_labels.
Validation of state value
State value of units and sensors can be validated before Universal Controller perform item update.
To validate item value, the following item properties are used:
- value_in_range_max value should be less
- value_in_range_max_eq value should be less or equal than specified max.
- value_in_range_min value should be greater
- value_in_range_min_eq value should be greater or equal than specified max.
or virtual parameter value_condition, which can be set in human readable way, e.g. 20<x<=200.
If value validation is set and item receive state value which is not numeric or doesn’t feet the specified range, item keep previous state value and get status -1 (error).
Item status is set back to normal as soon as any valid state update is received.
Logic variable
EVA Logic Manager uses the logic variables (lvars) to make decisions and organize production cycle timers.
The parameters of logic variables are set in their configurations.
Actually lvars are similar to sensors, but with the following differences:
- The system architecture implies that the sensor value is changed depending on the environment; the logic variables are set by the user or the system itself.
- The logic variables, as well as the sensors, have statuses -1, 0 and 1. However, if the status is 0 (variable is disabled) it stops responding to any value-only changes.
- The logic variables exchange two more parameters with the notification system: “expires” (time in seconds after the variable is set, and then takes the null value and -1 status) and set_time - time when the value was set for the last time.
The same logic variable may be declared on several logic controllers, but the “expires” configuration value should remain the same because each controller processes it autonomously. The variable becomes “expired” once it is declared as such by any controller.
Note
LVar doesn’t set its status to ‘-1’ on expires if its status is 0 (disabled)
The logic variable values may be synchronized via MQTT server or set via API or external scripts - similar to sensors.
You can use several logic variables as timers in order to organize production cycles. For example, there are three cycles: the pump No.1 operates in the first one, the pump No. 2 in the second one, and both pumps are disabled in the third one. In order to organize such cycle, let us create three variables: cycle1, cycle2, cycle_stop with “expires” values equal to the duration of each cycle in seconds.
Then - in the decision-making matrix you should specify the rules and macros run as soon as each cycle is finished. The macros run and stop the pumps as well as reset the timer variables of the next cycle: as soon as cycle_stop is finished, the pump No.1 is run, the cycle1 timer variable is reset; as soon as the cycle1 is finished, the pump No. 2 is run and cycle2 variable is reset; as soon as cycle2 is finished, both pumps are disabled and cycle_stop is reset.
In order to synchronize timer values with interfaces and the third-party applications, use LM API test command that displays the system information, including local time on the server on which the controller is installed.
However, when used in industrial configurations, it is recommended to synchronize time on all computers without any additional software hotfixes.
LVars in EVA hive
All logic variables have OIDs like lvar:group/lvar_id e.g. lvar:service/var1
For synchronization via MQTT, the following subjects are used for units
- [space/]lvar/<group>/<lvar_id>/status lvar status, integer
- [space/]lvar/<group>/<lvar_id>/value lvar value
- [space/]lvar/<group>/<lvar_id>/set_time last set time (Unix timestamp)
- [space/]lvar/<group>/<lvar_id>/expires value expiration time (seconds)
LVar parameters
As LVars behavior is similar to sensors except the values are set by user/system, they have the same parameters, except lvars can’t be updated via SNMP traps / MQTT.
Examples using LVars
You may use lvar as a
- Variable To use lvar as a shared variable to exchange some information between controllers, apps and SCADA interfaces, just set its value (and status if you want) and that’s it.
- Timer
- Set expires configuration param
- Use reset to set lvar status/value to 1 and reset the expiration timer
- Use clear to set lvar status to 0 and stop it reacting to expiration (when used with lvar which have expires param set, clear changes its status instead of value)
- Use decision rules with the conditions on_set and on_expire to run the macros when the timer is set/expired
- if the timer has status set to 1, it’s running
- if status is 0, it’s disabled with clear function
- if status is -1 and value is null (empty), the timer is expired
- Flag
- Use lvar as a simple boolean variable to exchange the information True/False, yes/no, enabled/disabled etc.
- Use reset to set lvar value to 1 which should be considered as True
- Use clear to set lvar value to 0 which should be considered as False
- Use toggle to toggle lvar value between 0 and 1
- Use constructions like if value(‘lvar_id’): in macros to determine is the ‘flag’ lvar is set or not.
Multi-updates
Multiupdates allow Universal Controller updating the state of several items with the use of one script. This could be reasonable in case all items are placed on the same bus or external controller and queried by a single command.
Multiupdate is an independent item in the system with its own configuration and without status and value. In turn, it updates statuses of the included items.
Multi-updates in EVA hive
All multi-updates have OIDs like mu:group/mu_id e.g. mu:environment/mu1
Multi-updates don’t have their own state, so they are not synchronized between servers.
Multiupdate parameters
Multi-updates have the same parameters as sensors, except that “expires”, “mqtt_update” and “snmp_trap”, plus some additional:
items = item1, item2, item3… - the list of items for updating, may be changed via UC API and eva uc as follows:
- -p “item+” -v “item_id” add item for update
- -p “item-” -v “item_id” delete item
- -p “items” -v “item1,item2,item3…” replace the whole list
update_allow_check - boolean, the multi-update will be performed only in case the passive state updates are currently allowed for all included items (i.e. if some of them run actions at this moment and have update_if_action=False, multi-update will be not executed)
Device
Multiple CVARs, units, sensors and multi-updates can be merged in logical groups called devices. It’s completely up to you how to merge items into device, but it’s recommended to keep them in one or several separate item groups.
Device templates are stored in runtime/tpl folder in YAML (default) or JSON format.
You can use uc-tpl command line tool to create device templates using the existing items and eva uc or device management UC API functions to create, update and destroy devices.
Device management requires master key or a key with allow=device permission.
Device example
Let’s imagine we have some hardware device, which has 1 relay and 2 sensors. We have a lot of devices like this and we want to create them using template.
Create one instance of device in Universal Controller defining all its items:
- sensor:device1/device1.sensor1
- sensor:device1/device1.sensor2
- unit:device1/device1.relay1
Configure all defined items, then run:
uc-tpl generate -i sensor:device1/device1.sensor1,sensor:device1/device1.sensor2,unit:device1/device1.relay1
This will output device JSON template. Use -t param to output template to file or copy/paste it from the screen. You can use -c param to ask the tool automatically prepare template variables, but in our example it will just replace all 1 to {{ ID }}. We don’t want it to be done this way because we have sensor1 and relay1 items, so let’s edit the template manually:
{
"sensors": [
{
"group": "device{{ ID }}",
"id": "device{{ ID }}.sensor1"
},
{
"group": "device{{ ID }}",
"id": "device{{ ID }}.sensor2"
}
],
"units": [
{
"group": "device{{ ID }}",
"id": "device{{ ID }}.relay1"
}
]
}
(template will also contain items’ configurations which are omitted in the example)
Save the final template as runtime/tpl/mydevice.json folder, and then
# execute this command to create new device "device5"
eva uc device create mydevice -C ID=5 -y
# execute this command to destroy "device5"
eva uc device destroy mydevice -C ID=5
Configurations of the newly created items of device5 are exact copies of the items of device1. The only configuration difference is the params where we’ve put template variables instead of part or full param value (in our example: {{ ID }}).
Note
Device templates are actually jinja2 templates, so you can use any jinja2 syntax in them (loops, conditions and etc.)
Device limitations
- Custom variables, units, sensors and multi-updates can be part of the device
- LVars can not be part of the device and Logic Manager doesn’t have any device management functions, but devices on the connected UCs can be created from logic control macros.
Drivers
Universal Controller uses 2 ways for controlling and monitoring items: item scripts and drivers. Drivers are the most advanced way, they are faster, contain all process logic and can be used to work with devices on a single bus, providing locking/unlocking mechanisms.
Code of driver is executed directly inside the controller core and unlike script can’t be terminated, unless it gets termination signal and decides to stop. If driver process causes timeout and there is no way to stop it, controller raises a critical exception and may terminate itself.
You should always use only reliable and tested drivers, otherwise your system may become unstable.
Structure
Each driver contains 2 modules: LPI (logical to physical interface) and PHI (physical interface). To load new driver into controller, follow the steps:
List the available PHI mods:
eva uc phi mods
Get PHI module information:
eva uc phi modinfo <phi_module>
If the desired PHI is not listed, download it and put to xc/drivers/phi folder. Official PHI modules are available at https://www.eva-ics.com/phi. You may either download the module manually or use
eva uc phi download <phi_module_uri>
command. Note that UC host doesn’t need to have a direct connection to the host you download PHI from, module is downloaded first to the host where eva CLI (or eva uc) is started, verified and then automatically uploaded to the controller.
Execute the command to list PHI configuration variables:
eva uc phi modhelp <phi_module> cfg
This will display the configuration variables, used when PHI is loaded (port numbers, default values etc.). Variables marked required=True should be always defined otherwise controller will fail to load PHI.
Load PHI with the following command:
eva uc phi load <phi_id> <phi_module> [-c config] [-y]
# example
eva uc phi load v1 vrtrelay -c default_status=1,update=5 -y
Param -y is used to ask the controller to save driver configuration right after PHI is loaded.
After the successful load, PHI will automatically create the most suitable driver for itself, called <phi_id>.default. This usually provides basic driver logic and doesn’t mean the driver is suitable for your task. You may replace it’s LPI module or define a different driver with another LPI.
To assign driver to the specified item, use the command:
eva uc driver assign <item_id> <driver_id> [-c config] [-y]
# example, set test_lamp to 5th relay port of driver v1
eva uc driver assign unit:lamps/test_lamp v1.default -c port=5
Param -y is used to ask the controller to save item configuration right after driver is assigned.
Param -c is used to set driver configuration for the specified item: set port, logic etc.
Advanced usage: EVA item can have different drivers or scripts for actions and updates. To assign different drivers, modify item properties action_exec, update_exec, action_driver_config and update_driver_config (e.g. with eva uc config props). Driver is assigned to the property with |driver_id value, e.g. |v1.default.
Note
All custom-defined user variables are always passed to driver function calls, which allows to set some device-specific or logic-specific options as global or for the particular item group.
How the driver handles action commands
Note that params started with _ are passed to PHI calls directly (without _ prefix), this allows specifying different hosts, bus addresses (if PHI is developed as “universal”) without a need to load different drivers for each item.
How the driver handles update commands
Use commands eva uc phi unload and eva uc phi unlink to unload and unlink unnecessary PHI modules, but note that driver and PHI can’t be unloaded while they’re assigned to items. You must first assign a different driver to the item or use eva uc driver unassign command.
You can load PHIs/drivers with the same IDs even if they are already present in the system without unloading them first. In this case, new modules/configuration replace the old ones.
Logical to physical interfaces (LPI)
LPI module handles the whole driver logic and doesn’t contain any code, specific for the equipment. All it needs is to process the logic and call the assigned PHI.
When the controller loads new PHI, it creates a driver called <phi_id>.default, assigning LPI to provide basic functionality, but you may want to replace it or use different logic for different items.
To list available LPI mods, use the command:
eva uc lpi mods
To get module information, use the command:
eva uc lpi modinfo <lpi_module>
Currently we don’t provide any additional LPI modules or SDK, all available mods are included in EVA ICS distribution.
To get additional module info, use the following commands:
# list module configuration options
eva uc lpi modhelp <lpi_module> cfg
# list module options used when action is called
eva uc lpi modhelp <lpi_module> action
# list module options used when state update is called
eva uc lpi modhelp <lpi_module> update
Configuration options are used when you load a driver (e.g. to modify LPI default behavior), separated with commas.
Action and update options are used when you assign a driver to the specified item; separate them with commas. Options marked required=True should be always defined.
Let’s see what modules are available.
basic LPI
Basic status on/off LPI module, used to control simple devices which have only status 0 (OFF) and 1 (ON), i.e. lamps, relay ports (directly) etc.
Used in default drivers for relay, sockets and similar PHIs, doesn’t need to be configured when loaded.
When assigning driver containing basic LPI mod to the specified item (eva uc driver assign), the assign configuration should contain port number (-c port=N) which usually matches the physical relay port.
Port number can be specified as a list (-c port=N1|N2|N3), in this case all listed ports will be used in commands.
Note
If relay port number is specified as i:N e.g. i:2, LPI commands will consider it is inverted meaning 0 is for on and 1 is for off. This works both for basic as well as for any other relay control LPI.
sensor LPI
Basic sensor monitiring, used to get data from specified sensors.
Used in default drivers for sensors, doesn’t need to be configured when loaded.
LPI doesn’t provide action functionality. When assigning driver containing sensor LPI mod to the specified item (eva uc driver assign), the assign configuration should contain port or bus address number.
ssp LPI
Similar to sensor LPI, but doesn’t contain any options at all. Used when PHI can work only with one physical equipment (e.g. sensor with TCP/IP API) and all equipment options are already set in PHI.
esensor LPI
Sensor monitoring with advanced functions. Can monitor physical sensor groups returning average, maximum or minimum value. Can ignore sensor values if they seem to be invalid in case one or several sensor in a group fail (while there are enough working sensors in a group).
Configuration options (set with eva uc driver load):
- skip_err If True, failed physical sensor in a group will be skipped, otherwise EVA sensor item gets error value.
- gpf Group port function, get values from the sensors in a group, then
return:
- avg average value
- max maximum value
- min minimum value
- first first available value from any working physical sensor
- max_diff maximum value difference until the sensor in a group is marked as failed and its value is ignored. E.g.: set this option 10 and let it poll the temperature sensors group. All sensors with temperature difference 10 degrees or more from the average are ignored.
Update options (set with eva uc driver assign):
- port driver port or ports (array). If you use multiple ports (group), they should be separated with pipes (|) for the items. Group separation for EVA multiupdate items should be made with double pipes (||)
- any configuration option (optional). E.g. if gpf=avg is defined, it overwrites default LPI behavior for the specified item.
multistep LPI
Module used for such common tasks as door or window opening. To use this module you must connect your equipment to 2 relay ports: one will give power to motors, the second will set the direction.
AC motor circuit
Configuration options (set with eva uc driver load):
- bose (break on state error). The module requires to know the current door or window position is. If you set this option to True and the current item status is error, the action will be not executed. Otherwise LPI will pass and consider the item status is 0.
- logic default or rdc (reversible DC motor circuit). If set to rdc, LPI will set port = 1, dport = 0 for “opening” and port = 0, dport = 1 for “closing”.
Reversible DC motor circiut
Action options (set with eva uc driver assign):
- port contains one or several (separated with |) relay ports used to power a motor (or plus for reversible DC).
- dport contains one or several (separated with |) relay ports used to set a direction (or minus for reversible DC).
- steps list of float numbers, contains time (in seconds) of power access period to the motor to reach the next step. E.g. you have a door with 3 positions: closed, half-open and completely open. steps option will contain 2 numbers (e.g. 20|25) which tells LPI the door state from 0 to 1 is changed by running motor for 20 seconds, the state from 1 to 2 is changed by running motor for 25 seconds, so LPI can automatically calculate the full opening/closing cycle is 45 seconds.
- warmup float number (seconds). LPI will add this value to the time for running the motor if the state is neither fully open nor fully closed, to let it “warm up” before doing actual work.
- tuning float number (seconds). LPI will add this value to the time, if action is open full or close full to make sure the door is fully open/closed.
- ts (to-start) number which indicates the following: e.g. you have a door with status from 0 (fully closed) to 5 (fully open) and defined the middle states with steps. But when calling action “set this door to 2” you can’t be sure the door position is equal when setting it from fully open and fully closed. But if you set e.g. ts=2 and the current status is greater than 2, it will tell LPi firstly to completely close the door (go to status=0) and then go to status=2.
- te (to-end) same as ts but in an opposite way: set the status number, starting from which the door will be fully open first, then go to the desired status.
Note
LPI will completely refuse to run the action if it calculates that therese is not enough time to complete it. Set unit action_timeout to the proper value.
Update options:
The module doesn’t provide any state update functionality. If you want to sync door/window item states with real, use separate reed switch sensor.
Loading driver with the chosen LPI
Firstly, you can list available LPIs with the command:
eva uc lpi mods
Consider the desired PHI is already loaded. To load the driver and combine PHI+LPI, use the command:
eva uc driver load <phi_id>.<lpi_id> <lpi_module> [-c config] [-y]
# in example, for PHI loaded as "v1":
eva uc driver load v1.ms multistep -c bose=true -y
Physical interfaces (PHI)
PHIs are modules, which contain no data processing logic but code to work directly with hardware equipment.
We provide a basic set of PHIs for the popular automation equipment (at https://www.eva-ics.com/phi), but if your equipment isn’t supported, it’s not so hard to develop your own PHI.
We’ve already described how to get and load PHIs, here is some additional important information.
Universal PHIs
If the word “universal” is listed in PHI features, it means the module can be loaded once and provide interface for all supported equipment. E.g. let’s take a look on sr201 PHI module which provides support for SR-201 compatible relays:
# get PHI module info
eva uc phi modinfo sr201
# get PHI configuration help
eva uc phi modhelp sr201 cfg
# get PHI options for obtaining the data
eva uc phi modhelp sr201 get
# get PHI options for setting the data
eva uc phi modhelp sr201 set
All of cfg, get and set have an option host which should be defined ether in PHI configutation (eva uc phi load with host config option or in item driver configuration (eva uc driver assign with _host config option). Setting different host option value in item driver configuration lets one sr201 PHI manage all available SR-201 relays.
Physical events
If the word “events” is listed in PHI features, it means the module can handle hardware events e.g. react to the alarm sensors or update item state when an external event is received.
How the driver handles physical events
In practice, it means PHI provides data, obtained from the hardware, to controller and asks it to update all items using drivers which contain PHI module which have an event.
When doing update, drivers LPI modules don’t ask PHI to get hardware data working only with data already provided by the hardware.
Drivers and multi updates
If the word “aao_get” is listed in PHI features, it means you don’t need to create multiupdates in Universal Controller to update several items at once. “aao_get” (all-at-once-get) means PHI can obtain all hardware data itself and then ask the controller to update all items using drivers which contain PHI equally to updating on physical events.
How to use this feature: All PHIs with “aao_get” feature also have configuration param named update which means how frequently (in seconds) PHI should collect data from the equipment and initiate item updates. update value should be defined in PHI load config and be greater than zero.
Example:
eva uc phi load relay2 sr201 -c host=192.168.20.2,update=5 -y
As soon as the driver is assigned to item (eva uc driver assign), it starts getting state updates every 5 seconds.
Testing PHIs and additional PHI commands
As soon as PHI is loaded, you can test how it works. All PHI modules respond to the command:
eva uc phi test <phi_id> self
which returns result “OK” or “FAILED”.
PHI can provide additional testing; to get a list of testing commands, execute:
eva uc phi test <phi_id> help
Some PHIs can provide additional commands to set up or control the hardware equipment. To get a list of these commands, execute:
eva uc phi exec <phi_id> help
Example: PHI module dae_ro16_modbus has a command to change Modbus unit ID of the hardware equipment. Let’s change unit ID to 5:
eva uc phi exec <phi_id> id 5
The module will flash new unit ID into hardware and change unit ID in self configuration. Don’t forget to restart the hardware to let it be accessed with new unit ID and save PHI config (eva uc save).
Item scripts
Item scripts are used to update items’ state and execute actions. Scripts are placed in xc folder (xc/uc for Universal Controller, xc/lm for Logic Manager) and may be either written in any scripting language or be binary executables. The script file should have exec permissions.
Universal Controller has 2 ways for controlling and monitoring items: drivers and item scripts. Sometimes item scripts are harder to implement as you must define all logic by yourself, as well as implement hardware calls, they are also slower because controller needs to execute an external process. But item scripts are more reliable than drivers because the external process can be easily terminated/killed by timeout, so if you don’t have a driver for your equipment or the driver is unstable, it is a good idea to use scripts.
All the examples provided in this documentation are written in the classic Bourne shell (bash). It is recommended to use dash or perl in heavy loaded production systems to provide better startup speed. Experience has shown that the modern systems do not require the use of the lower-level languages compiled into executable files: it complicates integration and servicing; on the other hand, the difference in program operation is only a few milliseconds.
The script always has max execution time (timeout) specified in item configuration (or default controller timeout). After that the system terminates the script operation: firstly - voluntary, by sending SIGTERM, then - forcibly by sending SIGKILL (this in-between time may be changed in item configuration with param term_kill_interval)
Script or program always gets the environment variables:
- all variables from the controller var file (uc_cvars or lm_cvars)
- PATH variable with additional EVA bin and xbin subfolders
- EVA_ITEM_ID item ID which the script is executed for
- EVA_ITEM_OID item OID (type:group/id)
- EVA_ITEM_TYPE item type: unit, sensor or lvar, (lvars can also be updated with scripts)
- EVA_ITEM_GROUP full item group
- EVA_ITEM_PARENT_GROUP the nearest parent group of the item (e.g. building1/env/room1/temp1 - room1)
- EVA_ITEM_FULL_ID full item ID
- EVA_ITEM_STATUS current item status
- EVA_ITEM_VALUE current item state value
The system considers the script to be successful if its exit code is 0.
Item actions
Item actions are used to control the units. After the unit action has been called, the controller executes the appropriate script. By default, control scripts are placed in xc/uc/ folder and named ID, where ID is a unit ID, for example, xc/uc/lamp1. This may be changed in the item configuration to let e.g. one script execute actions for a group of units.
The startup parameters of the action script include:
- param1 unit ID
- param2 new unit status
- param3 new unit value
Note
If unit action is called without value, action control script is called with previous known unit value
A simple example script: send toe command to X10 controller via mochad
#!/bin/sh
[ $2 -eq 0 ] && CMD="off" || CMD="on"
echo "pl $1 $CMD" | nc localhost 1099
Such script is actually universal for X10 (in case units are named according to X10 - a1-aX)
Another example: activate the third EG-PM2-LAN plug. Here we access EG1_IP variable from uc_cvars
#!/bin/sh
EG-PM2-LAN $EG1_IP 3 $2
Another example: control the relay (4 modules, 1 relay block) by Denkovi AE
#!/bin/sh
${RELAY1_CMD}.1.4.0 i $2
where in uc_cvars:
RELAY1_CMD = snmpset -v1 -c private RELAY_IP_ADDRESS .1.3.6.1.4.1.19865.1.2
In the previous examples, we used the same command for turning the units on/off. Let us review a more complex logic. The next example shows how EVA can shut down the remote server machine and turn it on via Wake on LAN (tip: such script requires more action_timeout in unit config):
#!/bin/sh
case $2 in
0)
ssh eva@${SERVER_IP} "sudo /sbin/poweroff"
;;
1)
wakeonlan ${SERVER_MAC}
;;
esac
In the queue history script is marked as completed if it completed independently with 0 code, failed - if the code differs from 0.
The script or program can display anything on stdout/stderr. This data, as well as the exit code, will be recorded in “out” and “err” fields of the result dict.
Sometimes it is useful to catch SIGTERM in the script/program, e.g. if you operate a motor that must be stopped after the script gets a termination signal. Warning:, the system does not track/stop child processes executed after SIGTERM is sent to the script.
Passive updates of item state
Passive updates are used to collect the state of the equipment which doesn’t report its state by itself. By default, scripts for passive updating of item state are named ID_update, where ID is a item ID, for example: lamp1_update.
The status update script is executed:
- Every X seconds, if update_interval specified in the config is more than 0
- After the unit action succeeds (if update_exec_after_action=true in config)
The system considers the script was executed successfully if its exit code is 0, otherwise, its new item state is ignored.
Passive update scripts get the following parameters:
- param1 “update”
- param2 item ID
Script should print on stdout only the new status and (optionally) value, separated by space, e.g.
0 NEW_VALUE
For the sensor, its data should be printed as:
1 VALUE
where 1 means the sensor is working properly.
Let us analyze an example of a simple script, e. g. state update of the sensor that monitors the remote machine
#!/bin/sh
ping -W1 -c1 ${SERVER_IP} > /dev/null 2>&1 && echo "1 1"||echo "1 0"
Unit status - the third EG-PM2-LAN plug
#!/bin/sh
EG-PM2-LAN evacc-rl5|cut -d, -f3
Update state of the relay (4 modules, 1 relay block) by Denkovi AE
#!/bin/sh
${RELAY1_UPDATE_CMD}.2.0|awk -F\ '{ print $4 }'
where in uc_cvars:
RELAY1_UPDATE_CMD = snmpget -v2c -c public RELAY_IP_ADDRESS .1.3.6.1.4.1.42505.6.2.3.1.3
Multiupdate scripts
Multiupdates allow updating the state of several items with one script which works like a normal passive update script and outputs the states of the monitored items line-by-line:
item1_status item1_value
item2_status item2_value
.....
The order of the output should correspond to the order of the items in the multiupdate.
By default, multiupdate scripts are named ID_update, where ID is a multiupdate ID, for example, xc/uc/temperatures_update for mu ID = temperatures.
For example, let’s update all 8 units connected to the relay controlled by DS2408
#!/bin/sh
w1_ds2408 28-999999999999 || exit 1
The script output will be as approximately follows:
1
0
1
1
1
1
0
1
where each row contains the status of the unit connected to the corresponding relay port.
Commands
Commands are used if you need to run some commands remotely on the server where EVA controller is installed. Commands are executed with controller cli tools, with SYS API function :ref:cmd<cmd> or with macro function.
For command scripts:
- Configurations are absent. Scripts are named as xc/cmd/SCRIPT_NAME
- Script timeout is set when it is started
Example of a command usage: a speaker is connected to a remote machine. We want to play some sound as an additional feedback after the certain macros or actions are executed
xc/cmd/play_snd
#!/bin/sh
GAIN=-7
killall play > /dev/null 2>&1 && killall -9 play > /dev/null 2>&1
play /data/snd/$1.wav gain ${GAIN}
when you call the command, the sound file_name will be played. If you want to wait until the playback is over add w=15 to API call i.e. to wait 15 seconds before continuing.
Modbus
Universal Controller provides native support of Modbus protocol for Modbus physical interfaces (PHIs). Core support is provided with pymodbus Python module, but with additional functionality, such as bus locking, automatic retry attempts, virtual ports for drivers etc.
Universal Controller works as Modbus master, connection links to all slave devices should be defined as virtual ports. After that, defined virtual ports and Modbus unit IDs should be set in corresponding PHI modules load configurations.
Defining Modbus virtual port
Before using any Modbus PHI, you must define Modbus virtual port. Modbus PHIs work with Modbus virtual ports only, while UC handles all hardware calls and responses.
List of the defined Modbus virtual ports can be obtained with command:
eva uc modbus list
To create new Modbus virtual port, execute the following command:
eva uc modbus create [-l] [-t SEC] [-r RETRIES] [-d SEC] [-y] ID PARAMS
where:
- -l lock port on operations, which means to wait while Modbus port is used by another controller thread (driver command)
- -t SEC Modbus operations timeout (in seconds, default: default timeout)
- -r RETRIES retry attempts for each operation (default: no retries)
- -d SEC delay between virtual port operations (default: 20ms)
- -y save Modbus port config after creation
- ID virtual port ID which will be used later in PHI configurations
- PARAMS Modbus params
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
As soon as the port is created, it can be used by PHI. Let’s create Modbus TCP port and load dae_ro16_modbus PHI module:
eva uc modbus create p1 tcp:192.168.11.11:502 -y
eva uc phi load r1 dae_ro16_modbus -c port=p1,unit=1 -y
As the result, controller creates a driver r1.default which can be set to item to work with any relay port of unit #1 of the Modbus relay 192.168.11.11 connected via TCP.
Warning
UC will grant Modbus port access to PHI only if it has enough timeout to wait for the longest possible call. It means operation timeout (action_timeout, update_timeout) in item should be greater than modbus_port_timeout*(1+modbus_port_retries). If the command max timeout is less than this value, attempts to access Modbus virtual port return an error.
If you need to change Modbus port params or options, you can always create new Modbus virtual port with the same ID, without deleting the previous one. Port configuration and options will be overwritten.
Testing Modbus virtual port
To test defined Modbus virtual port, execute the following command:
eva uc modbus test <ID>
# e.g.
eva uc modbus test p1
The command connects UC to Modbus port and checks the operation status.
Note
As Modbus UDP doesn’t require a port to be connected, test command always return “OK” result.
Deleting Modbus virtual port
To delete Modbus virtual port, execute the command:
eva uc modbus destroy <ID>
# e.g.
eva uc modbus destroy p1
Note that controller doesn’t check if the port is in use or not, so double check this manually before deleting it.
Modbus slave
Universal Controller can work as Modbus slave. Ports, the slave listens to, are set in etc/uc.ini. Modbus over TCP, UDP and serial ports (rtu/ascii/binary) is supported.
Controller uses single memory space for all ports it listens to, ports can have different Modbus addresses. Memory space has 10 000 holding registers, 10 000 coils, 10 000 input registers and 10 000 discrete inputs.
Units can listen to memory space changes and automatically update their status and value as soon as Modbus register is being changed. To activate state updates via Modbus slave memory space, set unit modbus_status and/or modbus_value properties to the corresponding registers, using before the number c for coil and h for holding register, e.g. c5 for 5th coil register, h50 for 50th holding register etc.
As Modbus values can be only integers, you may specify divider (or multiplier as well). To convert unsigned integer to signed, specify “S” before address. E.g. you have Modbus temperature sensor which stores its value every X seconds to holding register 5 on Universal Controller, multiplied by 100 and as signed integer. To automatically convert this value, set modbus_value = hS5/100
Sensors can update their value only. Don’t forget to enable sensor (set its status to 1) manually.
More complex data processing can be performed via PHI modules.
OWFS (1-Wire)
Universal Controller provides native support of 1-Wire technology for OWFS physical interfaces (PHIs). Core support is provided with OWFS.
For the simple setups, when 1-Wire bus is connected via system GPIO, PHIs can access it directly. But when 1-Wire is accessed via I2C, USB or other external bus, OWFS is preferred.
EVA ICS provides additional functionality for OWFS, such as bus locking, automatic retry attempts, virtual ports for drivers etc.
Defining OWFS bus
Before using any OWFS PHI, you must define OWFS bus. OWFS PHIs work with defined buses only, while UC handles all hardware calls and responses.
List of the defined OWFS buses be obtained with command:
eva uc owfs list
To define new OWFS bus, execute the following command:
eva uc owfs create [-h] [-l] [-t SEC] [-r RETRIES] [-d SEC] [-y] ID LOCATION
where:
- -l lock bus on operations, which means to wait while OWFS bus is used by another controller thread (driver command)
- -t SEC operations timeout (in seconds, default: default timeout)
- -r RETRIES retry attempts for each operation (default: no retries)
- -d SEC delay between operations (default: 50ms)
- -y save OWFS config after creation
- ID bus ID which will be used later in PHI configurations
- LOCATION OWFS location
OWFS location should contain the configuration of OWFS port. Actually it’s equal to standard OWFS params, except first – are not required:
# defines owfs bus on I2C#1
eva uc owfs create local1 "i2c=/dev/i2c-1:ALL" -y
# defines owfs bus on I2C#0 (force)
eva uc owfs create local2 "/dev/i2c-0 --w1" -y
# define owfs bus on local owserver
eva uc owfs create local3 localhost:4304 -y
As soon as the bus is defined, it can be used by PHI.
eva uc owfs scan local1 -a PIO
# 05.4AEC29CDBAAB DS2405
eva uc phi load relay1 ow_ds2405 -c owfs=local1,path=05.4AEC29CDBAAB -y
As the result, controller creates a driver relay.default which can be set to item.
Warning
UC will grant OWFS bus access to PHI only if it has enough timeout to wait for the longest possible call. It means operation timeout (action_timeout, update_timeout) in item should be greater than owfs_bus_timeout*(1+owfs_bus_retries). If the command max timeout is less than this value, attempts to access OWFS bus return an error.
If you need to change OWFS bus params or options, you can always define new OWFS bus with the same ID, without deleting the previous one. Bus configuration and options will be overwritten.
Scanning OWFS for devices
With scan command you can scan OWFS bus for the devices which have e.g. specified attributes:
eva uc owfs scan <ID> [options]
# e.g. let's find all 1-Wire equipment which has "temperature" property:
eva uc owfs scan local1 -a temperature
Deleting OWFS bus
To delete (undefine) OWFS bus, execute the command:
eva uc owfs destroy <ID>
# e.g.
eva uc owfs destroy local1
Note that controller doesn’t check if the port is in use or not, so double check this manually before deleting it.
Also note that some bus types lock system ow libraries and can not be recreated until Universal Controller process is restarted.
SNMP traps
Active item updates can be done using SNMP traps notifications.
Usually each automation device sends SNMP traps in its specific format and the data should be parsed individually for subsequent processing. You can use a third-party server to receive traps, for example, snmptrapd or trap handler included in EVA Universal Controller.
Built-in trap handler should be enabled in UC configuration file. Usually, SNMP traps server listen on the port 162. The embedded SNMP traps handler can work with SNMP v1 and SNMP v2c protocols.
Both units and sensors can update their state through SNMP traps processing. After the item configuration param snmp_trap is set up, it automatically subscribes to the incoming notifications and accept only the relevant ones.
Currently EVA works with SNMP OIDs only - all snmp variables should be created in this format. To change snmp_trap variable and its child elements you may use eva uc console app or UC API set_prop function. In this tutorial we’ll configure SNMP-traps handler with eva uc.
ident_vars - identifying the trap
snmp_trap.ident_vars variable is used by the handler to filter trap notifications and parse only those ones directly related to the item. You should use it if, for example, the source sends the state change notifications with the same OID for different items, but the trap contains some tokens or item IDs identifying that the notification is addressed to the particular item. You can set several ident vars (separated by a comma) at once. The notification will be processed only if all ident_vars match the trap.
Example:
eva uc config set unit1 snmp_trap.ident_vars 1.3.6.1.4.1.3856.1.7.11.0=14,1.3.6.1.4.1.3856.1.7.11.1=U1
Result:
eva uc -J config props unit1
{
"snmp_trap": {
"ident_vars": {
"1.3.6.1.4.1.3856.1.7.11.0": "14",
"1.3.6.1.4.1.3856.1.7.11.0": "U1"
},
}
}
To reset ident_vars variable, run the command without -v key.
set_down - handling the failures
When the controller receives trap notification indicating that the item is not available or disabled, its status is set to -1.
This can be made with set_down variable, which’s set similarly to ident_vars. If there are several OID, they should be listed and separated by commas when setting up. The handler assigns an error status to the item only if all set_down variables match the trap.
Example:
eva uc config set unit1 snmp_trap.set_down 1.3.6.1.4.1.3855.1.7.9.0=7
Result:
eva uc -J config props unit1
{
"snmp_trap": {
"set_down": {
"1.3.6.1.4.1.3855.1.7.9.0": "7"
}
}
To reset set_down variable, run the command without -v key.
set_status - setting the item status
If the source device sends trap notifications with variable having the item status in the format similar to EVA, the handler can immediately change the status to the assigned one. Each item can have only one set_status variable containing OID where item status is being set in a trap.
Example:
eva uc config set unit1 snmp_trap.set_status 1.3.6.1.4.1.3855.1.7.17.1
Result:
eva uc -J config props unit1
{
"snmp_trap": {
"set_status": "1.3.6.1.4.1.3855.1.7.17.1"
}
}
To reset set_status variable, run the command without -v key.
set_value - setting the item value
If the source device sends trap notifications with the variable having the item value (usually, these are various sensor controllers which e.g. send current temperature every minute), the handler can immediately change the value to the assigned one. Each item can have only one set_value variable containing OID where item value is set in a trap.
Example:
eva uc config set unit1 snmp_trap.set_value 1.3.6.1.4.1.3855.1.7.17.2
Result:
eva uc -J config props unit1
{
"snmp_trap": {
"set_value": "1.3.6.1.4.1.3855.1.7.17.2"
}
}
To reset set_value variable, run the command without -v key.
set_if - conditional state updates
If the received trap notification contains certain variables but none of them can be used to set status and/or value as-is, you can define your own rules and set the item status/value according to them.
This operates similarly to set_down, the only difference is that set_down sets the item status to -1, while set_if allows you to set the status and/or value on your own.
The variable is set as follows:
status,value:OID=val1,OID2=val2,OID3=val3
If you don’t need to set status or value, set it to null when defining.
For example, let’s add two conditions:
eva uc config set unit1 snmp_trap.set_if 1,null:1.3.6.1.4.1.3855.1.7.1.0=4
eva uc config set unit1 snmp_trap.set_if null,10:1.3.6.1.4.1.3855.1.7.1.0=2
Result:
eva uc -J config props unit1
{
"snmp_trap": {
"set_if": [
{
"value": "10",
"vars": {
"1.3.6.1.4.1.3855.1.7.1.0": "2"
}
},
{
"status": 1,
"vars": {
"1.3.6.1.4.1.3855.1.7.1.0": "4"
}
}]
}
}
When the controller receives a trap with OID 1.3.6.1.4.1.3855.1.7.1.0=2, the value of the item is set to 10. When OID 1.3.6.1.4.1.3855.1.7.1.0=4, the status is set to 1.
One item can have multiple set_if conditions but they can only be added. You can delete the condition only by deleting the entire set_if variable by running the command without -v key.
Disabling SNMP traps processing
To disable SNMP traps processing for a single item, delete its snmp_traps variable:
eva uc config set unit1 snmp_trap ''
Virtual items
Universal Controller items may be either virtual or real. You may toggle the item by changing configuration while the server is running.
Virtual drivers
If you want to build a virtual setup, the best idea is to use virtual drivers . EVA ICS distribution includes 2 virtual PHIs (drivers) which cover all typical needs:
- vrtrelay Virtual relay driver
- vrtsensors Virtual sensor pool driver
Both PHIs work like the real ones so all you need to switch your setup to production - assign “real” drivers to items or just load “real” PHIs with the same IDs.
Logic control macros
In Logic Manager macros can be triggered on the list of events, third-party applications or user via LM EI interface or LM API functions.
Macro code is a file written in Python and located in the folder xc/lm/ under the name <macro_id>.py, i.e. test.py for “test” macro. Macro id should be unique within the single LM PLC, full id (group/id) - within the whole installation.
Additionally, each macro is automatically appended with common.py file located in the same folder enabling to quickly assign common functions to several macros without using modules.
Macros are compiled into byte-code each time after macros file or common.py file are changed. Compilation or execution errors can be viewed in the log files of the controller.
Contents
- Logic control macros
- Executing macros
- Debugging macros
- Macros configuration
- Common principles of macros operation
- System macros
- Macros and security
- Macros built-ins
- Variables
- Extending macros functionality
- General functions
- alias - create object alias
- cmd - execute a remote system command
- date - date/time
- decrement_shared - decrement value of the shared variable
- exit - finish macro execution
- increment_shared - increment value of the shared variable
- ls - list files in directory
- mail - send email message
- open_newest - open newest file by mask
- open_oldest - open oldest file by mask
- run - execute another macro
- set_shared - set value of the shared variable
- shared - get value of the shared variable
- sleep - pause operations
- system - execute the command in a subshell
- time - current time in seconds since Epoch
- Item functions
- history - get lvar state history
- lvar_status - get lvar status
- lvar_value - get lvar value
- sensor_status - get sensor status
- sensor_value - get sensor value
- state - get item state
- status - get item status
- unit_nstatus - get unit nstatus
- unit_nvalue - get unit nvalue
- unit_status - get unit status
- unit_value - get unit value
- value - get item value
- LVar functions
- Unit control
- Rule management
- Scheduled job management
- Devices
- Logic cycles
- Locking functions
- Logging
Executing macros
To execute a macro, use macro run command of lm-cmd or LM API run function.
Debugging macros
Macro compilation and execution errors are written into the logs of the controller on DEBUG level, the exceptions are also added to err field of the execution result.
To receive information about errors you may run the following command:
lm-cmd -J run <macro_id> -w 3600 | jq -r .err
Macros configuration
After the macro code is placed into xc/lm/<macro_id>.py file, it should be appended to the controller using create_macro LM API function or with lm-cmd.
After the macro configuration is created, you may view its params using list_macro_props and change them with set_macro_prop.
Parameters:
- id macros id, can’t be modified after the macro is created
- action_enabled true means macro can be executed (true by default)
- action_exec controller gets the code of the macro from the file <macro_id>.py by default, use this parameter to assign another file
- description macro description
- group macro group (in difference to other objects, macro group can be changed after creation)
- pass_errors if true, in case the function called by macro is completed with an exception, the controller ignores this and continues the code execution (false by default)
- send_critical if true, allows to send critical events to controller core with critical(msg, send_event=True)
Common principles of macros operation
Macros are launched simultaneously: system does not wait for the completion of the macro and launches its next copy or another macro in parallel. If you want only one copy of macro to operate at the certain point of time or to block execution of other macros, use macro lock and unlock functions.
The system architecture does not provide the possibility to stop macro from outside, that is why macros should have minimum internal logic and cycles.
All the logic should be implemented in the decision-making matrix. The working cycles should be implemented with logic variables timers.
System macros
On startup
If defined, macro named system/autoexec is launched automatically at the controller startup. This macro is not always the first one executed, as far as some initial decision-making rules may call assigned macros, or some events may be handled before. In case a macro is launched later than logic variables or other loadable items update their status (e. g. due to slow connection with MQTT server) it’s recommended to use sleep function to do a small delay.
Macros from system group are considered as the local system macros and aren’t synchronized to SFA.
Example of autoexec macro usage:
# both cycle timers are expired
if is_expired('timers/timer1') and is_expired('timers/timer2'):
# launch the first cycle process
action('pumps/pump1', on)
# start the first cycle timer
reset('timers/timer1')
On shutdown
If defined, macro named system/shutdown is launched automatically at the controller startup. This macro can, for example, gracefully stop cycles and set/reset required logic variables. The macro should end its work in default controller timeout.
Macros and security
As all Python features are available for macros, including execution of external programs or working with any local files, the code of macros should be edited only by system administrator.
If access permissions to individual macros are configured via API keys, you should take into account the following: if a macro runs other macros using run function, these macros will be executed even if the API key allows to run only the initial macro.
Macros built-ins
Macros can execute any Python functions or use Python modules installed on the local server. In addition, macros have a set of built-in functions and variables.
Built-in functions are included for quick access to the most frequently used Python functions such as LM API and UC API. When calling API function, item id is always transmitted in full. When calling other macros and working with logic variables, it’s possible to use the short ids only.
Variables
Macros have the following built-in variables:
- on alias to integer 1
- off alias to integer 0
- yes alias to boolean True
- no alias to boolean False
- _source item generated the event, used by the system to call the macro. You may directly access the item and e.g. use its internal variables such as _source.item_id, _source.full_id, _source.oid etc.
- _polldelay controller poll delay
- _timeout controller default timeout
- args array list of arguments the macro is being executed with
- kwargs dict of keyword arguments the macro is being executed with
- _0 current macro id (i.e. ‘test’)
- _00 current macro full id (i.e. ‘group1/test’)
- _1, _2, … _9 first 9 arguments the macro is being executed with
- lm_cvars all lm_cvars variables
- out macro may use this variable to output the data which will be set to out field of the execution result
- is_shutdown if defined, contains a function which returns True if macro caller got shutdown/stop event (set by logic cycle)
Note
if macro arguments or lm_cvars are numbers, they are automatically converted to float type
Extending macros functionality
Macros function set can be extended with pre-made or custom macro extensions. As soon as extension is loaded, its functions become available in all macros without a need to restart LM PLC.
Also, macro can import any local Python module. The following modules are pre-imported:
- json JSON processing
- os standard Python OS functions
- requests HTTP functions
- sys standard Python system functions
General functions
alias - create object alias
alias('rpush', 'roboger_local_push')
Parameters:
- alias_obj alias object
- src_obj source object
Returns:
True if alias is set. Doesn’t raise any exceptions, safe to use in common files
cmd - execute a remote system command
Executes a command script on the server where the controller is installed.
r = cmd('uc/mws1-v1', 'test', wait=5)
Parameters:
- controller_id controller id to execute command on
- command name of the command script
Optionally:
- args string of command arguments, separated by spaces (passed to the script)
- wait wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- timeout maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
Returns:
Serialized command action object (dict)
{
"args": [],
"cmd": "test",
"err": "some text to stderr\n",
"exitcode": 0,
"out": "test script start\nparam 1: ( > 0 will generate \"failed\" status)\nparam 2: \nparam 3: \ndelay 3 sec\nscript finish\n",
"status": "completed",
"time": {
"completed": 1553466937.5606368,
"created": 1553466934.5421243,
"running": 1553466934.5424464
},
"timeout": 5.0
}
Raises:
- ResourceNotFound command script or controller is not found
date - date/time
r = date()
Returns:
Serialized date/time object (dict)
{
"day": 14,
"hour": 0,
"minute": 47,
"month": 5,
"second": 16,
"timestamp": 1557787636.680612,
"weekday": 1,
"year": 2019
}
ls - list files in directory
If recursive is true, the pattern “**” will match any files and zero or more directories and subdirectories.
r = ls('/opt/i/*.jpg')
Parameters:
- mask path and mask (e.g. /opt/data/*.jpg)
- recursive if True, perform a recursive search
Returns:
dict with fields ‘name’ ‘file’, ‘size’ and ‘time’ { ‘c’: created, ‘m’: modified }
[
{
"file": "/opt/i/20170926_004347.jpg",
"name": "20170926_004347.jpg",
"size": 6464873,
"time": {
"c": 1553460493.280853,
"m": 1506379536.0
}
},
{
"file": "/opt/i/20171017_095941.jpg",
"name": "20171017_095941.jpg",
"size": 1650389,
"time": {
"c": 1553460493.2968528,
"m": 1510695841.0
}
},
{
"file": "/opt/i/20171029_194029.jpg",
"name": "20171029_194029.jpg",
"size": 3440296,
"time": {
"c": 1553460493.324853,
"m": 1510695762.0
}
},
{
"file": "/opt/i/20170926_004334.jpg",
"name": "20170926_004334.jpg",
"size": 6523001,
"time": {
"c": 1553460493.1648533,
"m": 1506379526.0
}
}
]
mail - send email message
The function uses [mailer] section of the LM PLC configuration to get sender address and list of the recipients (if not specified).
mail(subject='we have a problem', text='sensor 5 is down')
Optionally:
- subject email subject
- text email text
- rcp recipient or array of the recipients
Raises:
- FunctionFailed mail is not sent
open_newest - open newest file by mask
i = open_newest('/opt/i/*.jpg', 'rb').read()
print(r)
None
Parameters:
- mask path and mask (e.g. /opt/data/*.jpg)
Optionally:
- mode file open mode (default: ‘r’)
Returns:
file descriptor
Raises:
- Exception exceptions equal to Python “open” function
open_oldest - open oldest file by mask
i = open_oldest('/opt/i/*.jpg', 'rb').read()
print(r)
None
Parameters:
- mask path and mask (e.g. /opt/data/*.jpg)
Optionally:
- mode file open mode (default: ‘r’)
Returns:
file descriptor
Raises:
- Exception exceptions equal to Python “open” function
run - execute another macro
Execute a macro with the specified arguments.
r = run('tests/test1', kwargs={'v1': 'test', 'v2': 999}, wait=2)
Parameters:
- macro macro id
Optionally:
- args macro arguments, array or space separated
- kwargs macro keyword arguments, name=value, comma separated or dict
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized macro action object (dict)
{
"args": [],
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0047829,
"item_group": "tests",
"item_id": "test1",
"item_oid": "lmacro:tests/test1",
"item_type": "lmacro",
"kwargs": {
"v1": "test",
"v2": 999
},
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869087.3697698,
"created": 1559869087.364987,
"pending": 1559869087.3653126,
"queued": 1559869087.3661342,
"running": 1559869087.3669574
},
"uuid": "fc0e8c8e-9c93-49c4-bb30-e7905fedc33f"
}
Raises:
- ResourceNotFound macro is not found
sleep - pause operations
Unlike standard time.sleep(…), breaks pause when controller shutdown event is received.
sleep(0.1)
Parameters:
- t number of seconds to sleep
- safe break on shutdown event (default is True)
Returns:
True if sleep is finished, False if shutdown event is received
system - execute the command in a subshell
r = system('touch /tmp/1.dat')
print(r)
0
Returns:
shell exit code (0 - no error)
time - current time in seconds since Epoch
Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.
r = time()
print(r)
1553461581.549374
Item functions
history - get lvar state history
r = history('lvar:tests/test1', t_start='2019-03-24')
Parameters:
- lvar_id lvar ID, or multiple IDs (list or comma separated)
Optionally:
- t_start time frame start, ISO or Unix timestamp
- t_end time frame end, optional (default: current time), ISO or Unix timestamp
- limit limit history records
- prop item property (‘status’ or ‘value’
- time_format time format, ‘iso’ or ‘raw’ (default) for timestamp
- fill fill frame with the specified interval (e.g. 1T - 1 minute, 2H - 2 hours etc.), optional. If specified, t_start is required
- fmt output format, ‘list’ (default) or ‘dict’
- db notifier ID which keeps history for the specified item(s) (default: db_1)
Returns:
list of dicts or dict of lists
{
"status": [
1,
1,
1,
1
],
"t": [
1553461864.9564857,
1553461878.8139935,
1553461883.1168087,
1553461887.6495461
],
"value": [
0.0,
0.0,
1.0,
1.0
]
}
lvar_status - get lvar status
r = lvar_status('tests/test1')
print(r)
1
Parameters:
- lvar_id lvar id
Returns:
lvar status (integer)
Raises:
- ResourceNotFound lvar is not found
lvar_value - get lvar value
r = lvar_value('tests/test1')
print(r)
1.0
Parameters:
- lvar_id lvar id
Returns:
lvar value
sensor_status - get sensor status
r = sensor_status('env/temp_test')
print(r)
1
Parameters:
- sensor_id sensor id
Returns:
sensor status (integer)
Raises:
- ResourceNotFound sensor is not found
sensor_value - get sensor value
r = sensor_value('env/temp_test')
print(r)
191.0
Parameters:
- sensor_id sensor id
Optionally:
- default value if null (default is empty string)
Returns:
sensor value
Raises:
- ResourceNotFound sensor is not found
state - get item state
r = state('sensor:env/temp1')
Parameters:
- item_id item id (oid required)
Returns:
item status/value dict
{
"status": 1,
"value": 55.0
}
Raises:
- ResourceNotFound item is not found
status - get item status
r = status('unit:tests/unit1')
print(r)
0
Parameters:
- item_id item id (oid required)
Returns:
item status (integer)
Raises:
- ResourceNotFound item is not found
unit_nstatus - get unit nstatus
nstatus is the status which is set to unit after the current running action is completed.
the function may be called with an alias “nstatus(…)”
r = unit_nstatus('tests/unit1')
print(r)
0
Parameters:
- unit_id unit id
Returns:
unit nstatus (integer)
Raises:
- ResourceNotFound unit is not found
unit_nvalue - get unit nvalue
nvalue is the value which is set to unit after the current running action is completed.
the function may be called with an alias “nvalue(…)”
r = unit_nvalue('tests/unit1')
print(r)
Parameters:
- unit_id unit id
Returns:
unit nvalue
Raises:
- ResourceNotFound unit is not found
unit_status - get unit status
r = unit_status('tests/unit1')
print(r)
0
Parameters:
- unit_id unit id
Returns:
unit status (integer)
Raises:
- ResourceNotFound unit is not found
unit_value - get unit value
r = unit_value('tests/unit1')
print(r)
Parameters:
- unit_id unit id
Optionally:
- default value if null (default is empty string)
Returns:
unit value
Raises:
- ResourceNotFound unit is not found
value - get item value
r = value('sensor:env/temp_test')
print(r)
191.0
Parameters:
- item_id item id (oid required)
Optionally:
- default value if null (default is empty string)
Returns:
item value
Raises:
- ResourceNotFound item is not found
LVar functions
clear - reset lvar value
Set lvar value to 0 or stop timer lvar (set timer status to 0)
clear('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
decrement - decrement lvar value
Decrement value of lvar. Initial value should be number
decrement('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value decrement error
- ResourceNotFound lvar is not found
expires - set lvar expiration time
expires('timers/timer1', 30)
Parameters:
- lvar_id lvar id
Optionally:
- etime time (in seconds), default is 0 (never expires)
Raises:
- FunctionFailed lvar expiration set error
- ResourceNotFound lvar is not found
increment - increment lvar value
Increment value of lvar. Initial value should be number
increment('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value increment error
- ResourceNotFound lvar is not found
is_expired - is lvar (timer) expired
r = is_expired('nogroup/timer1')
print(r)
True
Parameters:
- lvar_id lvar id
Returns:
True, if timer is expired
Raises:
- ResourceNotFound lvar is not found
reset - reset lvar value
Set lvar value to 1 or start lvar timer
reset('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
set - set lvar value
set('tests/test1', value=1)
Parameters:
- lvar_id lvar id
Optionally:
- value lvar value (if npt specified, lvar is set to null)
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
toggle - toggle lvar value
Change lvar value to opposite boolean (0->1, 1->0)
toggle('tests/test1')
Parameters:
- lvar_id lvar id
Raises:
- FunctionFailed lvar value set error
- ResourceNotFound lvar is not found
Unit control
action - unit control action
The call is considered successful when action is put into the action queue of selected unit.
r = action('tests/unit1', status=1, wait=5)
Parameters:
- unit_id unit id
- status desired unit status
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0149484,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869105.9634602,
"created": 1559869105.9485118,
"pending": 1559869105.9487257,
"queued": 1559869105.9491074,
"running": 1559869105.949467
},
"uuid": "4bce26a6-7203-4a3c-a123-14c144dcc613"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
action_toggle - toggle unit status
Create unit control action to toggle its status (1->0, 0->1). if using OID, you can also call “toggle(..)” with the same effect.
r = action_toggle('tests/unit1', wait=5)
Parameters:
- unit_id unit id
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 0,
"nvalue": "",
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1553465690.1327171,
"created": 1553465690.1081843,
"pending": 1553465690.1084123,
"queued": 1553465690.1089923,
"running": 1553465690.1094682
},
"uuid": "0982213a-6c8f-4df3-8581-d1281d0f41dc"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
is_busy - is unit busy
r = is_busy('tests/unit1')
print(r)
False
Parameters:
- unit_id unit id
Returns:
True, if unit is busy (action is executed)
Raises:
- ResourceNotFound unit is not found
kill - kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
kill('tests/unit1')
Parameters:
- unit_id unit id
Raises:
- ResourceNotFound unit is not found
q_clean - clean action queue of unit
Cancels all queued actions, keeps the current action running.
q_clean('tests/unit1')
Parameters:
- unit_id unit id
Raises:
- ResourceNotFound unit is not found
result - get action status
Checks the result of the action by its UUID or returns the actions for the specified unit.
r = result(unit_id='tests/unit1')
Parameters:
- unit_id unit id or
- uuid action uuid
Optionally:
- group filter by unit group
- status filter by action status: Q for queued, R for running, F for finished
Returns:
list or single serialized action object
[
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0147429,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 0,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869099.8924437,
"created": 1559869099.8777008,
"pending": 1559869099.8778677,
"queued": 1559869099.8782423,
"running": 1559869099.8786528
},
"uuid": "d5b82c8c-9a95-482a-9063-e3048addc741"
},
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0149484,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869105.9634602,
"created": 1559869105.9485118,
"pending": 1559869105.9487257,
"queued": 1559869105.9491074,
"running": 1559869105.949467
},
"uuid": "4bce26a6-7203-4a3c-a123-14c144dcc613"
}
]
Raises:
- ResourceNotFound unit or action is not found
start - start unit
Create unit control action to set its status to 1
r = start('tests/unit1', wait=5)
Parameters:
- unit_id unit id
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0179181,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869092.8558156,
"created": 1559869092.8378975,
"pending": 1559869092.838309,
"queued": 1559869092.8390505,
"running": 1559869092.8402033
},
"uuid": "bf74b19c-2af1-40f6-9ec6-5f74bb572558"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
stop - stop unit
Create unit control action to set its status to 0
r = stop('tests/unit1', wait=5)
Parameters:
- unit_id unit id
Optionally:
- value desired unit value
- wait wait for the completion for the specified number of seconds
- uuid action UUID (will be auto generated if none specified)
- priority queue priority (default is 100, lower is better)
Returns:
Serialized action object (dict)
{
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0147429,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 0,
"nvalue": null,
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559869099.8924437,
"created": 1559869099.8777008,
"pending": 1559869099.8778677,
"queued": 1559869099.8782423,
"running": 1559869099.8786528
},
"uuid": "d5b82c8c-9a95-482a-9063-e3048addc741"
}
Raises:
- FunctionFailed action is “dead”
- ResourceNotFound unit is not found
terminate - terminate action execution
Terminates or cancel the action if it is still queued
try:
terminate(unit_id='tests/unit1')
except ResourceNotFound:
print('no action running')
Parameters:
- unit_id action uuid or
- uuid unit id
Raises:
- ResourceNotFound if unit/action is not found or action is already finished
Rule management
set_rule_prop - set rule prop
set_rule_prop('28af95b2-e087-47b3-a6cd-15fe21d06c4a', 'condition', 'x < 5')
Parameters:
- rule_id rule id (uuid)
- prop property to set
- value value to set
Optionally:
- save save rule config after the operation
Raises:
- ResourceNotFound rule is not found
Scheduled job management
set_job_prop - set job prop
set_job_prop('6970e296-5cb4-4448-9f2a-1ab2a14ed7f1', 'enabled', True)
Parameters:
- job_id job id (uuid)
- prop property to set
- value value to set
Optionally:
- save save job config after the operation
Raises:
- ResourceNotFound job is not found
Devices
deploy_device - deploy device items from template
Deploys the device from the specified template.
deploy_device('uc/mws1-v1', 'device1', cfg={ 'ID': 5 })
Parameters:
- controller_id controller id to deploy device on
- device_tpl device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- cfg device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
Raises:
- ResourceNotFound device template or controller is not found
- FunctionFailed device deploy error
undeploy_device - undeploy device items config from template
undeploy_device('uc/mws1-v1', 'device1', cfg={ 'ID': 5 })
Parameters:
- controller_id controller id to deploy device on
- device_tpl device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- cfg device config (var=value, comma separated or dict)
Raises:
- ResourceNotFound device template or controller is not found
update_device - update device items config from template
update_device('uc/mws1-v1', 'device1', cfg={ 'ID': 5 })
Parameters:
- controller_id controller id to deploy device on
- device_tpl device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- cfg device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
Raises:
- ResourceNotFound device template or controller is not found
- FunctionFailed device update error
Logic cycles
get_cycle_info - get cycle information
r = get_cycle_info('tests/cycle1')
Parameters:
- cycle_id cycle id
Returns:
dict with cycle information
{
"avg": 0.01,
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"ict": 20,
"id": "cycle1",
"interval": 0.01,
"iterations": 0,
"macro": "tests/test",
"oid": "lcycle:tests/cycle1",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "0,0.0100,"
}
Raises:
- ResourceNotFound cycle is not found
is_cycle_running - get cycle running status
r = is_cycle_running('tests/cycle1')
print(r)
True
Parameters:
- cycle_id cycle id
Returns:
True if cycle is runing
Raises:
- ResourceNotFound cycle is not found
list_cycle_props - list cycle props
r = list_cycle_props('tests/cycle1')
Parameters:
- cycle_id cycle id
Returns:
dict with cycle props
{
"autostart": false,
"description": "",
"ict": 20,
"interval": 0.01,
"macro": "tests/test",
"on_error": null
}
Raises:
- ResourceNotFound cycle is not found
reset_cycle_stats - reset cycle stats
reset_cycle_stats('tests/cycle1')
Parameters:
- cycle_id cycle id
Raises:
- ResourceNotFound cycle is not found
set_cycle_prop - set cycle prop
set_cycle_prop('tests/cycle1', 'ict', 20)
Parameters:
- cycle_id cycle id
- prop property to set
- value value to set
Optionally:
- save save cycle config after the operation
Raises:
- ResourceNotFound cycle is not found
start_cycle - start cycle
start_cycle('tests/cycle1')
Parameters:
- cycle_id cycle id
Raises:
- ResourceNotFound cycle is not found
stop_cycle - stop cycle
stop_cycle('tests/cycle1', wait=True)
Parameters:
- cycle_id cycle id
Optionally:
- wait wait for cycle stop (default is False)
Raises:
- ResourceNotFound cycle is not found
Locking functions
lock - acquire lock
lock('lock1', expires=1)
Parameters:
- l lock id
Optionally:
- timeout max timeout to wait
- expires time after which token is automatically unlocked (if absent, token may be unlocked only via unlock function)
Returns:
True if lock is acquired
Raises:
- FunctionFailed function failed to acquire lock
unlock - release lock
Releases the previously acquired lock.
unlock('lock1')
Parameters:
- l lock id
Returns:
True if lock is released
Raises:
- ResourceNotFound lock is not found
- FunctionFailed function failed to release lock
Logging
debug - put debug message to log file
debug('this is a test debug message')
Parameters:
- m message text
info - put info message to log file
Additionally, print() function is alias to info()
info('this is a test debug message')
Parameters:
- m message text
warning - put warning message to log file
info('this is a test debug message')
Parameters:
- m message text
error - put error message to log file
error('this is a test debug message')
Parameters:
- m message text
critical - put critical message to log file
critical('this is a test debug message')
Parameters:
- m message text
Optionally:
- send_event if True, critical event to core is sent (requires send_critical=true in macro props)
Decision-making matrix
Decision-making matrix is a set of rules and conditions under that Logic Manager runs the specified macros when certain events occur.
To manage the decision rules you may use eva lm (lm-cmd) console applications, LM API functions or an appropriate LM EI interface section.
Rule configuration is stored in runtime/lm_dmatrix_rule.d/ folder.
Event analysis algorithms
Event means any change of the item state. The events are analyzed and processed in the following way:
A specific ID is assigned to each event by which you can monitor its processing in the logs.
The system takes the list of all rules sorted by their priority (the lower the value, the higher the priority) and description.
Each rule is analyzed separately, in the order of priority
Firstly, it’s checked whether the rule corresponds to the type, group, ID and property of the item that sent the event
Then, the system is verifying whether the current item state matches the rule conditions and the previous one is out of its range
- For example, there is a temperature sensor; the condition 25 <= x <= 28 is specified in the rule; it will match only once - as soon as the transmitted temperature reaches 25-28 degrees. The rule will match again if the temperature exceeds this range and returns back.
- When the controller is just started, the previous state is unknown or usually outdated. In this case, the system acts according to the configuration property of the rule for_initial: if it’s set to skip, the rule is ignored, if only or any, it’s verified and the rule matches if the current state matches the range.
- If for_initial is set to only in the rule configuration, the rule is being checked only once, after the controller is started and the initial states of the items are received.
- Logic variables always have an initial value stored in the local base, that’s why for_initial should always be any for them to let the rules work correctly, unless you really know what you do.
- If the rule matches, a macro (if specified) with the specified arguments is executed.
- If chillout_time > 0 in the configuration, the rule is ignored after the match for the specified time.
Rule configuration
Unmodifiable rule parameters:
- id rule id, always generated automatically when it is created
- chillout_ends_in a virtual parameter specifying for how long (in seconds) the rule is ignored, if chillout_time is set
Modifiable Parameters:
- break_after_exec if True and the rule matches, further rules for the event are ignored
- chillout_time the rule is ignored for a specified time (in seconds) after match
- condition “virtual” parameter which allows get/set rule condition in the readable format (e.g. 25 < x <= 28)
- description rule description
- enabled if True, rule is enabled (new rules are disabled by default)
- for_initial can be skip, only or any (default is any). Indicates the rule processing algorithm when the server is started and the initial item states are received
- for_item_group the rule matches only for a specific group of items ((# or null - for all groups)
- for_item_id the rule matches only for a specific item (# or null - for all items), may contain the mask *id, id* or *id*, i.e. *.temperature
- for_prop the state property of the item (status or value) the rule is checking. For unit state, nstatus and nvalue properties may be additionally used.
- in_range_max matches when x < value
- in_range_max_eq matches when x <= value (in_range_max should be specified)
- in_range_min matches when x > value
- in_range_min_eq matches when x >= value (in_range_min should be specified)
- macro macro that is executed when the rule conditions match
- macro_args arguments the macro is executed with
- macro_kwargs keyword arguments the macro is executed with
- priority the rule priority (integer; the lower the value, the higher the priority, 100 by default)
Tips for rule configuration
- to set “x == value” condition via lm_api: if the value is numeric, use “value <= x <= value”. If the value is string, you may set only in_range_min_eq
- if you set a field for_expire (with any value, i.e. Y) in a rule change request, the system automatically sets the rule to for_prop = status, x <= -1, which means the rule match when the item state is expired. This is useful to configure the rule to check for the lvar timers expiration as well as checking for units and sensors error states
- if you set a field for_set (with any value, i.e. Y) in a rule change request, the system automatically sets the rule to for_prop = status, x == 1, which means the rule match when the item state is set. This is useful to configure the rule to check for the lvar timers reset as well as working with a logical flags
- if the rule has no in_range_min and in_range_max conditions, it will match each time when the item changes its status (for_prop == status) or value (for_prop == value)
Scheduled jobs
Scheduled jobs are similar to decision-making rules except they’re triggered when the specified time comes.
To manage scheduled jobs you may use eva lm (lm-cmd) console applications, LM API functions or an appropriate LM EI interface section.
Jobs configuration is stored in runtime/lm_job.d/ folder.
Job configuration
- description job description
- enabled if True, job is enabled (new jobs are disabled by default)
- every schedule interval
- macro macro that is executed
- macro_args arguments the macro is executed with
- macro_kwargs keyword arguments the macro is executed with
Job schedule interval
Schedule interval (every parameter) is set in a human-readable format. Examples:
- second execute job every second
- 5 seconds execute job every 5 seconds
- 2 minutes at :30 execute job every 2 minutes at 30th second
- 5 hours execute job every 5 hours
- 2 days execute job every 2 days
- wednesday at 13:15 execute job every Wednesday at 13:15
Logic cycles
Logic Manager allows to define logic cycles. Logic cycle is a loop which run specified macro as a worker with a chosen interval.
Logic Manager can create new cycles, start, stop them and reset their stats. Cycle information is replicated to SCADA Final Aggregator nodes, however SFA can access logic cycles read-only.
Cycle control from SFA nodes (and UI) is possible only by calling pre-made LM PLC macros, which can use macro control functions to manage cycles.
Note
For the heavy industry processes we strongly recommend to use dedicated hardware production cycle controllers and control/monitor them using EVA ICS as a supervisor only.
Parameters
Each lcycle object has the following parameters:
autostart cycle will start automatically as soon as LM PLC server is started
avg (read-only) real average cycle interval
ict interval correction. LM PLC will try correcting cycle interval every ict iterations to keep it real-time as max as possible. Additionally, during the correction LM PLC will replicate cycle state (iterations, avg) with connected SFA nodes (cycle status is replicated in real-time)
iterations (read-only) cycle iterations since the last start/stats reset
interval cycle interval, in seconds
macro macro, which is called as a worker
on_error macro, which is called if cycle error has been occurred
status (read-only) cycle status, changed when start/stop commands are executed. Can be:
- 0 cycle is stopped
- 1 cycle is running
- 2 cycle got “stop” command and will stop as soon as current iteration finish
value (read-only) contains iterations and avg values, comma separated
Note
When cycle is running, attempts to change parameters ict, interval or macro will return an error.
on_error macro
Macro, defined in on_error cycle property is called when:
- exception worker macro raised an exception, on_error macro args
contain:
- _1 “exception” word
- _2 exception object
- timeout/exec error macro execution took more time than cycle loop
interval is set to, or worker macro exited with non-zero code. on_error
macro args contain:
- _1 “timeout” or “exec_error” word
- _2 serialized worker macro execution result
the macro can e.g. stop cycle execution, send critical event to controller core or just log an error and let cycle continue.
Performance
Theoretically, cycle interval can be up to 1ms (1kHz worker frequency), but don’t expect stable cycle loops on a slow/busy hardware. In real life, software controllers handle well production loops up to 200/300ms (3-5Hz), with lower values (~100ms = 10Hz) users may expect 2-3% of iteration loss. Stable logic-rich cycles with the interval, lower than 20ms (50Hz), are nearly impossible.
If worker macro perform a calls between EVA ICS nodes, don’t forget about network timeouts.
To let cycle run with a maximum precision and avoid timeout errors, it is strongly recommended for the low-interval cycles:
- set up dedicated LM PLC instance
- turn off controller logging
- turn off controller action history (set keep_action_history to 0)
- if worker macro performs calls to Universal Controller, make sure controlled unit state isn’t replicated to other nodes in real-time via notifiers or stored in any state history databases (make dedicated group for such units and don’t subscribe notifiers to it)
- read common recommendations about using EVA ICS in high-load environments.
SFA Templates
SCADA Final Aggregator uses jinja2 template engine to serve server-side templates. You can use SFA templates for regular HTML, javascript and JSON data files. Both ui and pvt folders can contain template files, the difference is only that templates in ui are public while templates in pvt are served via SFA PVT.
Template files
All files with .j2 extension are processed as templates, index.j2 has more priority than index.html as the primary interface page.
Templates support all jinja2 functions and features, plus have some specific built-in variables and functions.
Template variables
The following variables are available in all templates:
- All custom user-defined variables
- server contains a dict with a system and current API key info (equal to SFA API test function result) plus an additional key remote_ip which contains either request IP address or value of X-Real-IP variable (if set by frontend server).
- request contains CherryPy request object, e.g. display user agent:
{{ request.headers.get('User-Agent') }}
Template functions
All templates have the following built-in functions. Template functions never raise exceptions, instead they return None values.
groups
Get list of item groups
groups(g=None, p=None, k=None)
where:
- g filter by group (use MQTT-style wildcards)
- p item type (U for unit, S for sensor, LV for lvar), required
- k API key (use key ID instead of key itself)
The function is similar to SFA API groups except that if API key is not specified, the current key is used.
state
Get list of items and their state
state(i=None, g=None, p=None, k=None):
where:
- i full item id (group/id), optional
- g filter by group (use MQTT-style wildcards)
- p item type (U for unit, S for sensor, LV for lvar), required
- k API key (use key ID instead of key itself)
The function is similar to SFA API state except that if API key is not specified, the current key is used.
api_call
Allows to call any SFA API method directly.
api_call(method, params={}, k=None)
where:
- method API method to call
- params API call parameters
- k API key (use key ID instead of key itself)
Example. Let’s warn user when specified UC controller is not connected:
{%- set controller = api_call(
'get_controller', { 'i': 'uc/mws1-v1' }, 'masterkey') %}
{%- if not controller.connected %}
UC controller is not connected
{%- endif %}
SFA PVT
While developing the interfaces for SCADA Final Aggregator you face the issue of the private data protection: the UI is loaded with the javascript application that runs in the browser and requires authentication to access the SFA API functions. However, the application may contain components which an unauthorized user should not see: plans of the building, security cam footages, even the list of the managed items may be confidential.
One way to solve this problem is to use the frontend server for such content. However, frontend is not always necessary and, in our case, the content structure often requires the access rights to certain parts to be set on the front-end. Therefore, it may involve duplicating user base and difficult integration of the additional authentication methods.
In most cases, it would be sufficient to delineate access to such content with the help of SFA PVT server. The access rights to the certain files and catalogs are regulated with pvt parameter in SFA API keys.
The PVT server interface is available at http(s)://<IP_address_SFA:Port>/pvt, and the private content should be placed in pvt folder of EVA root directory.
pvt parameter of API keys supports MQTT-style wildcards, i.e.:
pvt = map.jpg, c1/#, +/content.js
will give the key access to map.jpg, all files and subfolders of c1 folder as well as content.js file in any first-level folder.
If the client is authenticated in advance, the future requests do not require k=APIKEY param.
Contents
Loading files from PVT Server
The file can be loaded with the following request:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=FILE
where
- k valid API key
- f a full relative file path, i.e. map.jpg or c2/content.js
Receiving the file list
Use c=list request param to receive the file list by the specified mask:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=FILEMASK&c=list
The mask should be included in the pvt key access right parameter, for example
pvt = c1/*.json ; or c1/# for all files and masks
The complete request example:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=c1/*.png&c=list
which return JSON array:
[{
"name": "1.png",
"size": 2443,
"time": {
"c": 1507735364.2441583,
"m": 1507734605.1451921
}
},
{
"name": "2.png",
"size": 2231,
"time": {
"c": 1507735366.5561802,
"m": 1507735342.923956
}
}]
where
- size file size (in bytes)
- time/c inode creation time (ctime, UNIX timestamp)
- time/m file modification time (mtime)
Receiving the newest and the oldest file
Use c=newest (c=oldest) param to do the typical job of the management interfaces - receiving the newest file from the specified folder.
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=FILEMASK&c=newest
Example: there is a monitoring camera that uploads a file to the folder on the server every 10 seconds. The uploaded files are named, i.e. TIMESTAMP.jpg or ID.jpg.
Connect the file with these images to pvt:
cd pvt
ln -sf /path/to/camerafolder cam1
and easily receive the newest file with the following request:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=cam1/*.jpg&c=newest
Image Processing
Use ic=resize to ask the server to preprocess the image file. To let the server process images, Python PIL (pillow) library should be installed. EVA installer automatically installs the library using pip3.
Please, make sure that system has at least libjpeg-dev and libjpeg8-dev before EVA setup, otherwise, PIL won’t work with JPEG images.
In case you miss this and server returns an error (“decoder not available”), reinstall pillow:
<EVA_DIR>/python3/bin/pip3 install --no-cache-dir -I pillow
If everything is installed correctly, you can receive the processed image using the following request:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=FILE&ic=resize:XxYxQ:encoder
where:
- X and Y - image maximum width/height
- Q image quality
- encode image encoder
I.e. let’s get an image pvt/cam/1.jpg, resize it to 800x600 as max, and convert to JPEG with 90% quality:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=cam1/1.jpg&ic=resize:800x600x90:jpeg
We may combine ic with c param, allowing us to receive the newest file by the mask. The request
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=cam1/*.jpg&c=newest&ic=resize:800x600x50:jpeg
will return the newest jpeg file from cam1 folder having scaled the image size to max 800x600 (proportionally) and reduced its quality to 50%. If the newest file cannot be processed (for example, the image isn’t completely loaded by cam yet and the file is locked), the server will attempt to process the previous one.
If the content is processed immediately before its loading by the interface, the server won’t need to generate the unnecessary images, especially if every client demands a specific format.
The maximum size of source file for the image processing is 10 megabytes.
Disabling cache
To ensure the request cashing is disabled, add nocache parameter with any value:
http(s)://<IP_address_SFA:Port>/pvt?k=APIKEY&f=FILE&nocache=VALUE
if you use this parameter for requests, web browser will not cache a file (if random value is used). Besides, the server will set Cache-Control, Expires and Pragma headers to the values which prohibit any caching.
Using frontend
If you work via frontend, you can use the pvt folder as a usual one (in case the authentication succeeded) by accessing files by their path without f parameter. Example for NGINX:
location / {
rewrite ^/pvt/(.+)$ /pvt?f=$1 last;
}
The additional commands will keep working:
GET "http://eva.sfa.domain/pvt/data/cam3/*.jp*?c=newest&ic=resize:320x200x50:jpeg&nocache=1508070344872"
Remote content
SFA PVT can act as a proxy, fetching allowed resources in local network and displaying them to user.
This can be done with request
http(s)://<IP_address_SFA:Port>/rpvt?k=APIKEY&f=http://remote_host/folder/file&nocache=some_random_value
Param nocache is optional. If user is logged in, param k can be omitted.
Example: you have a chart on storage server in local network displaying storage usage. The chart is located at http://192.168.1.20/charts/zfs.png
Append the following permission string to API key:
rpvt = 192.168.1.20/charts/#
This will grant access to all files on the specified host in /charts/ folder.
Then include remote chart in your interface:
<img src="/rpvt?k=APIKEY&f=192.168.1.20/charts/zfs.png" />
As you see, the remote client doesn’t need to have a direct access to 192.168.1.20 web server, /rpvt API call acts for him as a content proxy.
To use remote content feature, you must follow the rules:
- protocol (http/https) doesn’t need to be specified in rpvt API key param.
- f param of /rpvt request may contain uri protocol (e.g. http://192.168.1.20/charts/zfs.png). If the protocol is not specified, SFA uses plain HTTP without SSL.
- You can not specify http(s) port in f param of /rpvt unless it’s also specified in rpvt API key param.
- ic option is used for image processing, same as for local PVT file.
- Avoid using rpvt = #, this will allow /rpvt to work as http proxy for any local and Internet resource and may open a security hole.
API session tokens
Special API methods login and logout (present in all EVA ICS APIs, /r/token resource for RESTful) allow to open API session and use server-generated API token instead of API key.
To enable tokens, set parameter session_timeout greater than zero in [webapi] section of controller configuration (enabled in SFA by default).
Also, API session tokens are required by EVA JS Framework, which uses them to handle interface sessions.
Usage
Token has no restrictions and can be used as usual API key, the only one difference is that token has expiration time or can be purged by owner earlier.
SFA Templates and SFA PVT methods additionally accept authentication tokens set in auth cookie. After successful login, EVA JS Framework automatically set this cookie for URI paths /ui, /pvt and /rpvt.
Expiration
Token will expire and become invalid, if:
- it hasn’t been used for a time, longer, than specified session_timeout
- the time, passed since token generation is greater than session_timeout and session_no_prolong = yes is set in controller configuration
- API method logout (DELETE /r/token for RESTful) was called
- on any API key modification, which is token assigned to
- on any user account modification, which is token assigned to (if token was obtained with user credentials)
- controller has been restarted.
Mobile clients
Android
EVA ICS Control Center client
You can use official EVA ICS Control Center client to access SFA UI from Android-based mobile phones.
The client is evaHI-based application, so it can be configured in the same way
SFA automatically maps ui/.evahi directory to /.evahi URI. If front-end server is used, URI should be accessible without user authentication to let all application features work properly.
EVA JS Framework function $eva.hiQR can be used to generate configuration QR code for the current authenticated user.
Building own client
You can easily build custom Android client for your EVA ICS UI, customizing application class, name, menu, icons. Please refer to evaHI building instructions.
Authentication
evaHI sends username/password only if basic authentication is set up. However API login method automatically detects evaHI client (by HTTP User-Agent header) and ask it to provide authentication credentials.
If there is no front-end with basic authentication set up for all clients, you may display log in form for all, but let evaHI-based clients to try logging in automatically via EVA JS Framework:
if ($eva.in_evaHI) {
$eva.start();
} else {
// show login form
}
Apple iOS and other mobile platforms
Currently we have no plans to release native iOS client, iPhone users may access SFA UI via 3rd-party apps or built-in mobile browser.
SYS API
SYS API is a common API present in all EVA controllers. SYS API functions are used to manage controller itself.
RESTful API equivalent calls can be found in corresponding component RESTful API docs.
API basics
Standard API (direct method calling)
SYS API functions are called through URL request
http://<ip_address:port>/sys-api/function
If SSL is allowed in the controller configuration file, you can also use https calls.
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Standard API responses
Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.
API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.
Standard responses in status/body:
- 200 OK { “result”: “OK” } API call completed successfully.
Standard error responses in status:
- 400 Bad Request Invalid request params
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found method or resource/object doesn’t exist
- 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
In case API function has been failed, response body will contain JSON data with _error field, which contains error message.
{
"_error": "unable to add object, already present",
"result": "ERROR"
}
JSON RPC
Additionally, API supports JSON RPC 2.0 protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” }). There’s no error result, as JSON RPC sends errors in “error” field.
If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.
Note
JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.
JSON RPC API URL:
http://<ip_address:port>/jrpc
JSON RPC error responses
JSON RPC calls return error codes equal to the codes of EVA API Client:
- 1 the item or resource is not found
- 2 access is denied with the set API key
- 6 Attempt to call undefined API method/function
- 10 API function failed (all errors not listed here fall within this category)
- 11 API function is called with invalid params
- 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
- 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
- 14 the method is not implemented in/for requested resource
Response field “message” may contain additional information about error.
Contents
- SYS API
- API basics
- General functions
- CVARs
- Locking functions
- Logging
- log - put message to log file
- log_debug - put debug message to log file
- log_info - put info message to log file
- log_warning - put warning message to log file
- log_error - put error message to log file
- log_critical - put critical message to log file
- log_get - get records from the controller log
- log_rotate - rotate log file
- API keys
- User accounts
- Notifier management
- File management
General functions
test - test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
POST /sys-api/test HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/test -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/test --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/test Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/test', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"db_update": 1,
"debug": true,
"file_management": true,
"layout": "enterprise",
"polldelay": 0.001,
"product_build": 2019031405,
"product_code": "uc",
"product_name": "EVA Universal Controller",
"result": "OK",
"setup_mode": false,
"system": "mws1-v1",
"time": 1552863476.453035,
"uptime": 521,
"version": "3.2.0"
}
Parameters:
- k any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
save - save database and runtime configuration
All modified items, their status, and configuration will be written to the disk. If exec_before_save command is defined in the controller’s configuration file, it’s called before saving and exec_after_save after (e.g. to switch the partition to write mode and back to read-only).
http
POST /sys-api/save HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/save -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/save --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/save Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/save', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
cmd - execute a remote system command
Executes a command script on the server where the controller is installed.
http
POST /sys-api/cmd HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "c": "test", "a": "0 2 3", "w": 5, "t": 10 }
curl
curl -i -X POST http://localhost:8812/sys-api/cmd -H 'Content-Type: application/json' --data-raw '{"a": "0 2 3", "c": "test", "k": "mykey", "t": 10, "w": 5}'
wget
wget -S -O- http://localhost:8812/sys-api/cmd --header='Content-Type: application/json' --post-data='{"a": "0 2 3", "c": "test", "k": "mykey", "t": 10, "w": 5}'
httpie
echo '{
"a": "0 2 3",
"c": "test",
"k": "mykey",
"t": 10,
"w": 5
}' | http POST http://localhost:8812/sys-api/cmd Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/cmd', headers={
'Content-Type': 'application/json',
}, json={
'a': '0 2 3',
'c': 'test',
'k': 'mykey',
't': 10,
'w': 5,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"args": [
"0",
"2",
"3"
],
"cmd": "test",
"err": "some text to stderr\n",
"exitcode": 0,
"out": "test script start\nparam 1: 0 ( > 0 will generate \"failed\" status)\nparam 2: 2\nparam 3: 3\ndelay 3 sec\nscript finish\n",
"status": "completed",
"time": {
"completed": 1552863480.690193,
"created": 1552863480.681957,
"running": 1552863480.682348
},
"timeout": 10.0
}
Parameters:
- k API key with allow=cmd permissions
- c name of the command script
Optionally:
- a string of command arguments, separated by spaces (passed to the script)
- w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
set_debug - switch debugging mode
Enables and disables debugging mode while the controller is running. After the controller is restarted, this parameter is lost and controller switches back to the mode specified in the configuration file.
http
POST /sys-api/set_debug HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "debug": true }
curl
curl -i -X POST http://localhost:8812/sys-api/set_debug -H 'Content-Type: application/json' --data-raw '{"debug": true, "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_debug --header='Content-Type: application/json' --post-data='{"debug": true, "k": "mykey"}'
httpie
echo '{
"debug": true,
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/set_debug Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_debug', headers={
'Content-Type': 'application/json',
}, json={
'debug': True,
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- debug true for enabling debug mode, false for disabling
shutdown_core - shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
http
POST /sys-api/shutdown_core HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/shutdown_core -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/shutdown_core --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/shutdown_core Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/shutdown_core', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
login - log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /sys-api/login HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8812/sys-api/login -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8812/sys-api/login --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8812/sys-api/login Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/login', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- k valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
logout - log out and purge authentication token
Purges authentication token
http
POST /sys-api/logout HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7" }
curl
curl -i -X POST http://localhost:8812/sys-api/logout -H 'Content-Type: application/json' --data-raw '{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
wget
wget -S -O- http://localhost:8812/sys-api/logout --header='Content-Type: application/json' --post-data='{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
httpie
echo '{
"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
}' | http POST http://localhost:8812/sys-api/logout Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/logout', headers={
'Content-Type': 'application/json',
}, json={
'k': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid token
CVARs
get_cvar - get the value of user-defined variable
Note
Even if different EVA controllers are working on the same server, they have different sets of variables To set the variables for each subsystem, use SYS API on the respective address/port.
http
POST /sys-api/get_cvar HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_cvar -H 'Content-Type: application/json' --data-raw '{"i": "test", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_cvar --header='Content-Type: application/json' --post-data='{"i": "test", "k": "mykey"}'
httpie
echo '{
"i": "test",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/get_cvar Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_cvar', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- k API key with master permissions
Optionally:
- i variable name
Returns:
Dict containing variable and its value. If no varible name was specified, all cvars are returned.
set_cvar - set the value of user-defined variable
http
POST /sys-api/set_cvar HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test", "v": "some_value" }
curl
curl -i -X POST http://localhost:8812/sys-api/set_cvar -H 'Content-Type: application/json' --data-raw '{"i": "test", "k": "mykey", "v": "some_value"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_cvar --header='Content-Type: application/json' --post-data='{"i": "test", "k": "mykey", "v": "some_value"}'
httpie
echo '{
"i": "test",
"k": "mykey",
"v": "some_value"
}' | http POST http://localhost:8812/sys-api/set_cvar Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_cvar', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test',
'k': 'mykey',
'v': 'some_value',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i variable name
Optionally:
- v variable value (if not specified, variable is deleted)
Locking functions
get_lock - get lock status
http
POST /sys-api/get_lock HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "mylock1" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_lock -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "mylock1"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_lock --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "mylock1"}'
httpie
echo '{
"k": "mykey",
"l": "mylock1"
}' | http POST http://localhost:8812/sys-api/get_lock Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_lock', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'l': 'mylock1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"locked": true,
"type": "lock"
}
Parameters:
- k API key with allow=lock permissions
- l lock id
lock - acquire lock
Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:
- centralized for several systems (any EVA server can act as lock server)
- removed from outside
- automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock
used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.
Note
Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.
http
POST /sys-api/lock HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "mylock1", "e": 1, "t": 15 }
curl
curl -i -X POST http://localhost:8812/sys-api/lock -H 'Content-Type: application/json' --data-raw '{"e": 1, "k": "mykey", "l": "mylock1", "t": 15}'
wget
wget -S -O- http://localhost:8812/sys-api/lock --header='Content-Type: application/json' --post-data='{"e": 1, "k": "mykey", "l": "mylock1", "t": 15}'
httpie
echo '{
"e": 1,
"k": "mykey",
"l": "mylock1",
"t": 15
}' | http POST http://localhost:8812/sys-api/lock Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/lock', headers={
'Content-Type': 'application/json',
}, json={
'e': 1,
'k': 'mykey',
'l': 'mylock1',
't': 15,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with allow=lock permissions
- l lock id
Optionally:
- t maximum time (seconds) to acquire lock
- e time after which lock is automatically released (if absent, lock may be released only via unlock function)
unlock - release lock
Releases the previously acquired lock.
http
POST /sys-api/unlock HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "mylock1" }
curl
curl -i -X POST http://localhost:8812/sys-api/unlock -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "mylock1"}'
wget
wget -S -O- http://localhost:8812/sys-api/unlock --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "mylock1"}'
httpie
echo '{
"k": "mykey",
"l": "mylock1"
}' | http POST http://localhost:8812/sys-api/unlock Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/unlock', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'l': 'mylock1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with allow=lock permissions
- l lock id
Logging
log - put message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "warning", "m": "local file system is full" }
curl
curl -i -X POST http://localhost:8812/sys-api/log -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "warning", "m": "local file system is full"}'
wget
wget -S -O- http://localhost:8812/sys-api/log --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "warning", "m": "local file system is full"}'
httpie
echo '{
"k": "mykey",
"l": "warning",
"m": "local file system is full"
}' | http POST http://localhost:8812/sys-api/log Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'l': 'warning',
'm': 'local file system is full',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- l log level
- m message text
log_debug - put debug message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_debug HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test debug message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_debug -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test debug message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_debug --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test debug message"}'
httpie
echo '{
"k": "mykey",
"m": "test debug message"
}' | http POST http://localhost:8812/sys-api/log_debug Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_debug', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'test debug message',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_info - put info message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_info HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test info message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_info -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test info message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_info --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test info message"}'
httpie
echo '{
"k": "mykey",
"m": "test info message"
}' | http POST http://localhost:8812/sys-api/log_info Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_info', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'test info message',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_warning - put warning message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_warning HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test warning message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_warning -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test warning message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_warning --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test warning message"}'
httpie
echo '{
"k": "mykey",
"m": "test warning message"
}' | http POST http://localhost:8812/sys-api/log_warning Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_warning', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'test warning message',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_error - put error message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_error HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test error message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_error -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test error message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_error --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test error message"}'
httpie
echo '{
"k": "mykey",
"m": "test error message"
}' | http POST http://localhost:8812/sys-api/log_error Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_error', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'test error message',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_critical - put critical message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_critical HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test critical message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_critical -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test critical message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_critical --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test critical message"}'
httpie
echo '{
"k": "mykey",
"m": "test critical message"
}' | http POST http://localhost:8812/sys-api/log_critical Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_critical', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'test critical message',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_get - get records from the controller log
Log records are stored in the controllers’ memory until restart or the time (keep_logmem) specified in controller configuration passes.
http
POST /sys-api/log_get HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "warning", "t": 3600, "n": 3 }
curl
curl -i -X POST http://localhost:8812/sys-api/log_get -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "warning", "n": 3, "t": 3600}'
wget
wget -S -O- http://localhost:8812/sys-api/log_get --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "warning", "n": 3, "t": 3600}'
httpie
echo '{
"k": "mykey",
"l": "warning",
"n": 3,
"t": 3600
}' | http POST http://localhost:8812/sys-api/log_get Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_get', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'l': 'warning',
'n': 3,
't': 3600,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"h": "mws1-v1",
"l": 30,
"mod": "sysapi",
"msg": "test warning message",
"p": "uc",
"t": 1552863481.1394246,
"th": "CP Server Thread-15"
},
{
"h": "mws1-v1",
"l": 40,
"mod": "sysapi",
"msg": "test error message",
"p": "uc",
"t": 1552863481.1516943,
"th": "CP Server Thread-16"
},
{
"h": "mws1-v1",
"l": 50,
"mod": "sysapi",
"msg": "test critical message",
"p": "uc",
"t": 1552863481.1631815,
"th": "CP Server Thread-17"
}
]
Parameters:
- k API key with sysfunc=yes permissions
Optionally:
- l log level (10 - debug, 20 - info, 30 - warning, 40 - error, 50 - critical)
- t get log records not older than t seconds
- n the maximum number of log records you want to obtain
log_rotate - rotate log file
Equal to kill -HUP <controller_process_pid>.
http
POST /sys-api/log_rotate HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_rotate -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_rotate --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/log_rotate Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_rotate', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
API keys
create_key - create API key
API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.
Keys with master permission can not be created.
http
POST /sys-api/create_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey", "save": true }
curl
curl -i -X POST http://localhost:8812/sys-api/create_key -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/sys-api/create_key --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey", "save": true}'
httpie
echo '{
"i": "testkey",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/sys-api/create_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/create_key', headers={
'Content-Type': 'application/json',
}, json={
'i': 'testkey',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey",
"items": [],
"key": "c143d2e3a484e165a8d243395702bef6821b933ca7bc93ee5011ad02cb6ea36d",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": false
}
Parameters:
- k API key with master permissions
- i API key ID
- save save configuration immediately
Returns:
JSON with serialized key object
destroy_key - delete API key
http
POST /sys-api/destroy_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/destroy_key -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/destroy_key --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey"}'
httpie
echo '{
"i": "testkey",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/destroy_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/destroy_key', headers={
'Content-Type': 'application/json',
}, json={
'i': 'testkey',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i API key ID
list_key_props - list API key permissions
Lists API key permissons (including a key itself)
Note
API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.
http
POST /sys-api/list_key_props HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_key_props -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_key_props --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey"}'
httpie
echo '{
"i": "testkey",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_key_props Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_key_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'testkey',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey",
"items": [],
"key": "c143d2e3a484e165a8d243395702bef6821b933ca7bc93ee5011ad02cb6ea36d",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- k API key with master permissions
- i API key ID
- save save configuration immediately
list_keys - list API keys
http
POST /sys-api/list_keys HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_keys -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_keys --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_keys Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_keys', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"dynamic": false,
"key_id": "masterkey",
"master": true
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": true,
"groups": [
"#"
],
"items": [],
"key_id": "default",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "lm",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": true,
"lock": true
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "operator",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "sfa",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [
"item1"
],
"key_id": "t4",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [],
"items": [
"sensor:sensors/sensor1"
],
"key_id": "test",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": true,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey2",
"master": false,
"sysfunc": true
}
]
Parameters:
- k API key with master permissions
regenerate_key - regenerate API key
http
POST /sys-api/regenerate_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/regenerate_key -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/regenerate_key --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey"}'
httpie
echo '{
"i": "testkey",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/regenerate_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/regenerate_key', headers={
'Content-Type': 'application/json',
}, json={
'i': 'testkey',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "28baa61356c0b583c8286063fa7836c2c16fc3c2dc45325d00bd2363f3ef128b"
}
Parameters:
- k API key with master permissions
- i API key ID
Returns:
JSON dict with new key value in “key” field
set_key_prop - set API key permissions
http
POST /sys-api/set_key_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey", "save": true, "p": "sysfunc", "v": true }
curl
curl -i -X POST http://localhost:8812/sys-api/set_key_prop -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey", "p": "sysfunc", "save": true, "v": true}'
wget
wget -S -O- http://localhost:8812/sys-api/set_key_prop --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey", "p": "sysfunc", "save": true, "v": true}'
httpie
echo '{
"i": "testkey",
"k": "mykey",
"p": "sysfunc",
"save": true,
"v": true
}' | http POST http://localhost:8812/sys-api/set_key_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_key_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'testkey',
'k': 'mykey',
'p': 'sysfunc',
'save': True,
'v': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i API key ID
- p property
- v value (if none, permission will be revoked)
- save save configuration immediately
User accounts
create_user - create user account
Note
All changes to user accounts are instant, if the system works in read/only mode, set it to read/write before performing user management.
http
POST /sys-api/create_user HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test", "p": "verysecretpassword", "a": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/create_user -H 'Content-Type: application/json' --data-raw '{"a": "testkey", "k": "mykey", "p": "verysecretpassword", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/create_user --header='Content-Type: application/json' --post-data='{"a": "testkey", "k": "mykey", "p": "verysecretpassword", "u": "test"}'
httpie
echo '{
"a": "testkey",
"k": "mykey",
"p": "verysecretpassword",
"u": "test"
}' | http POST http://localhost:8812/sys-api/create_user Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/create_user', headers={
'Content-Type': 'application/json',
}, json={
'a': 'testkey',
'k': 'mykey',
'p': 'verysecretpassword',
'u': 'test',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test"
}
Parameters:
- k API key with master permissions
- u user login
- p user password
- a API key to assign (key id, not a key itself)
destroy_user - delete user account
http
POST /sys-api/destroy_user HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test" }
curl
curl -i -X POST http://localhost:8812/sys-api/destroy_user -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/destroy_user --header='Content-Type: application/json' --post-data='{"k": "mykey", "u": "test"}'
httpie
echo '{
"k": "mykey",
"u": "test"
}' | http POST http://localhost:8812/sys-api/destroy_user Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/destroy_user', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'u': 'test',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- u user login
get_user - get user account info
http
POST /sys-api/get_user HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_user -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_user --header='Content-Type: application/json' --post-data='{"k": "mykey", "u": "test"}'
httpie
echo '{
"k": "mykey",
"u": "test"
}' | http POST http://localhost:8812/sys-api/get_user Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_user', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'u': 'test',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test"
}
Parameters:
- k API key with master permissions
- u user login
list_users - list user accounts
http
POST /sys-api/list_users HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_users -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_users --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_users Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_users', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"key": "test",
"user": "divisor"
},
{
"key": "testkey",
"user": "test"
},
{
"key": "testkey",
"user": "test2"
}
]
Parameters:
- k API key with master permissions
set_user_key - assign API key to user
http
POST /sys-api/set_user_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test", "a": "masterkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/set_user_key -H 'Content-Type: application/json' --data-raw '{"a": "masterkey", "k": "mykey", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_user_key --header='Content-Type: application/json' --post-data='{"a": "masterkey", "k": "mykey", "u": "test"}'
httpie
echo '{
"a": "masterkey",
"k": "mykey",
"u": "test"
}' | http POST http://localhost:8812/sys-api/set_user_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_user_key', headers={
'Content-Type': 'application/json',
}, json={
'a': 'masterkey',
'k': 'mykey',
'u': 'test',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- u user login
- a API key to assign (key id, not a key itself)
set_user_password - set user password
http
POST /sys-api/set_user_password HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test", "p": "qwerty" }
curl
curl -i -X POST http://localhost:8812/sys-api/set_user_password -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "qwerty", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_user_password --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "qwerty", "u": "test"}'
httpie
echo '{
"k": "mykey",
"p": "qwerty",
"u": "test"
}' | http POST http://localhost:8812/sys-api/set_user_password Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_user_password', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'qwerty',
'u': 'test',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- u user login
- p new password
Notifier management
disable_notifier - disable notifier
Note
The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.
http
POST /sys-api/disable_notifier HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "eva_1" }
curl
curl -i -X POST http://localhost:8812/sys-api/disable_notifier -H 'Content-Type: application/json' --data-raw '{"i": "eva_1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/disable_notifier --header='Content-Type: application/json' --post-data='{"i": "eva_1", "k": "mykey"}'
httpie
echo '{
"i": "eva_1",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/disable_notifier Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/disable_notifier', headers={
'Content-Type': 'application/json',
}, json={
'i': 'eva_1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i notifier ID
enable_notifier - enable notifier
Note
The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.
http
POST /sys-api/enable_notifier HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "eva_1" }
curl
curl -i -X POST http://localhost:8812/sys-api/enable_notifier -H 'Content-Type: application/json' --data-raw '{"i": "eva_1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/enable_notifier --header='Content-Type: application/json' --post-data='{"i": "eva_1", "k": "mykey"}'
httpie
echo '{
"i": "eva_1",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/enable_notifier Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/enable_notifier', headers={
'Content-Type': 'application/json',
}, json={
'i': 'eva_1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i notifier ID
get_notifier - get notifier configuration
http
POST /sys-api/get_notifier HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "eva_1" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_notifier -H 'Content-Type: application/json' --data-raw '{"i": "eva_1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_notifier --header='Content-Type: application/json' --post-data='{"i": "eva_1", "k": "mykey"}'
httpie
echo '{
"i": "eva_1",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/get_notifier Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_notifier', headers={
'Content-Type': 'application/json',
}, json={
'i': 'eva_1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
Parameters:
- k API key with master permissions
- i notifier ID
list_notifiers - list notifiers
http
POST /sys-api/list_notifiers HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_notifiers -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_notifiers --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_notifiers Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_notifiers', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"db": "db1.db",
"enabled": true,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
}
],
"id": "db_1",
"keep": 86400,
"type": "db"
},
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
]
Parameters:
- k API key with master permissions
File management
file_put - put file to runtime folder
Puts a new file into runtime folder. If the file with such name exists, it will be overwritten. As all files in runtime are text, binary data can not be put.
http
POST /sys-api/file_put HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script", "m": "/bin/sh\n\nexit 0" }
curl
curl -i -X POST http://localhost:8812/sys-api/file_put -H 'Content-Type: application/json' --data-raw '{"i": "xc/uc/test_action_script", "k": "mykey", "m": "/bin/sh\n\nexit 0"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_put --header='Content-Type: application/json' --post-data='{"i": "xc/uc/test_action_script", "k": "mykey", "m": "/bin/sh\n\nexit 0"}'
httpie
echo '{
"i": "xc/uc/test_action_script",
"k": "mykey",
"m": "/bin/sh\n\nexit 0"
}' | http POST http://localhost:8812/sys-api/file_put Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_put', headers={
'Content-Type': 'application/json',
}, json={
'i': 'xc/uc/test_action_script',
'k': 'mykey',
'm': '/bin/sh\n\nexit 0',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
- m file content
file_set_exec - set file exec permission
http
POST /sys-api/file_set_exec HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script", "e": true }
curl
curl -i -X POST http://localhost:8812/sys-api/file_set_exec -H 'Content-Type: application/json' --data-raw '{"e": true, "i": "xc/uc/test_action_script", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_set_exec --header='Content-Type: application/json' --post-data='{"e": true, "i": "xc/uc/test_action_script", "k": "mykey"}'
httpie
echo '{
"e": true,
"i": "xc/uc/test_action_script",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/file_set_exec Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_set_exec', headers={
'Content-Type': 'application/json',
}, json={
'e': True,
'i': 'xc/uc/test_action_script',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
- e false for 0x644, true for 0x755 (executable)
file_get - get file contents from runtime folder
http
POST /sys-api/file_get HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script" }
curl
curl -i -X POST http://localhost:8812/sys-api/file_get -H 'Content-Type: application/json' --data-raw '{"i": "xc/uc/test_action_script", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_get --header='Content-Type: application/json' --post-data='{"i": "xc/uc/test_action_script", "k": "mykey"}'
httpie
echo '{
"i": "xc/uc/test_action_script",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/file_get Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_get', headers={
'Content-Type': 'application/json',
}, json={
'i': 'xc/uc/test_action_script',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"data": "/bin/sh\n\nexit 0",
"e": false,
"file": "xc/uc/test_action_script"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
file_unlink - delete file from runtime folder
http
POST /sys-api/file_unlink HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script" }
curl
curl -i -X POST http://localhost:8812/sys-api/file_unlink -H 'Content-Type: application/json' --data-raw '{"i": "xc/uc/test_action_script", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_unlink --header='Content-Type: application/json' --post-data='{"i": "xc/uc/test_action_script", "k": "mykey"}'
httpie
echo '{
"i": "xc/uc/test_action_script",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/file_unlink Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_unlink', headers={
'Content-Type': 'application/json',
}, json={
'i': 'xc/uc/test_action_script',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
UC API
Universal Controller API is used to control and manage units and sensors
This document describes API methods for direct and JSON RPC calls. For RESTful API look UC RESTful API.
API basics
Standard API (direct method calling)
UC API functions are called through URL request
http://<ip_address:8812>/uc-api/function
If SSL is allowed in the controller configuration file, you can also use https calls.
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Standard API responses
Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.
API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.
Standard responses in status/body:
- 200 OK { “result”: “OK” } API call completed successfully.
Standard error responses in status:
- 400 Bad Request Invalid request params
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found method or resource/object doesn’t exist
- 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
In case API function has been failed, response body will contain JSON data with _error field, which contains error message.
{
"_error": "unable to add object, already present",
"result": "ERROR"
}
JSON RPC
Additionally, API supports JSON RPC 2.0 protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” }). There’s no error result, as JSON RPC sends errors in “error” field.
If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.
Note
JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.
JSON RPC API URL:
http://<ip_address:8812>/jrpc
JSON RPC error responses
JSON RPC calls return error codes equal to the codes of EVA API Client:
- 1 the item or resource is not found
- 2 access is denied with the set API key
- 6 Attempt to call undefined API method/function
- 10 API function failed (all errors not listed here fall within this category)
- 11 API function is called with invalid params
- 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
- 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
- 14 the method is not implemented in/for requested resource
Response field “message” may contain additional information about error.
Contents
- UC API
- API basics
- General functions
- Item functions
- action - unit control action
- action_toggle - toggle unit status
- disable_actions - disable unit actions
- enable_actions - enable unit actions
- groups - get item group list
- kill - kill unit actions
- q_clean - clean action queue of unit
- result - get action status
- start_item_maintenance - start item maintenance mode
- state - get item state
- state_history - get item state history
- stop_item_maintenance - stop item maintenance mode
- terminate - terminate action execution
- update - update the status and value of the item
- Item management
- list - list items
- create - create new item
- create_mu - create multi-update
- create_sensor - create new sensor
- create_unit - create new unit
- destroy - delete item or group
- get_config - get item configuration
- list_props - list item properties
- save_config - save item configuration
- set_prop - set item property
- clone - clone item
- clone_group - clone group
- 1-Wire bus via OWFS
- Modbus ports
- create_modbus_port - create virtual Modbus port
- destroy_modbus_port - delete virtual Modbus port
- get_modbus_port - get virtual Modbus port configuration
- list_modbus_ports - list virtual Modbus ports
- read_modbus_port - read Modbus register(s) from remote slave
- test_modbus_port - test virtual Modbus port
- write_modbus_port - write Modbus register(s) to remote slave
- get_modbus_slave_data - get Modbus slave data
- Physical interfaces (PHIs)
- exec_phi - execute additional PHI commands
- get_phi_ports - get list of PHI ports
- list_phi - list loaded PHIs
- list_phi_mods - get list of available PHI modules
- load_phi - load PHI module
- modhelp_phi - get PHI usage help
- modinfo_phi - get PHI module info
- phi_discover - discover installed equipment supported by PHI module
- put_phi_mod - upload PHI module
- set_phi_prop - set PHI configuration property
- test_phi - test PHI
- unlink_phi_mod - delete PHI module file
- unload_phi - unload PHI
- LPI and drivers
- assign_driver - assign driver to item
- get_driver - get loaded driver information
- list_drivers - list loaded drivers
- list_lpi_mods - get list of available LPI modules
- load_driver - load a driver
- modhelp_lpi - get LPI usage help
- modinfo_lpi - get LPI module info
- set_driver_prop - set driver (LPI) configuration property
- unload_driver - unload driver
- Devices
General functions
test - test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
POST /uc-api/test HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/test -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"db_update": 1,
"debug": true,
"file_management": true,
"layout": "enterprise",
"polldelay": 0.001,
"product_build": 2019031405,
"product_code": "uc",
"product_name": "EVA Universal Controller",
"result": "OK",
"setup_mode": false,
"system": "mws1-v1",
"time": 1552867566.8738406,
"uptime": 990,
"version": "3.2.0"
}
Parameters:
- k any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
login - log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /uc-api/login HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8812/uc-api/login -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8812/uc-api/login --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8812/uc-api/login Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/login', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- k valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
logout - log out and purge authentication token
Purges authentication token
http
POST /uc-api/logout HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7" }
curl
curl -i -X POST http://localhost:8812/uc-api/logout -H 'Content-Type: application/json' --data-raw '{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
wget
wget -S -O- http://localhost:8812/uc-api/logout --header='Content-Type: application/json' --post-data='{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
httpie
echo '{
"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
}' | http POST http://localhost:8812/uc-api/logout Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/logout', headers={
'Content-Type': 'application/json',
}, json={
'k': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid token
Item functions
action - unit control action
The call is considered successful when action is put into the action queue of selected unit.
http
POST /uc-api/action HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "s": 1 }
curl
curl -i -X POST http://localhost:8812/uc-api/action -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "s": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/action --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "s": 1}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"s": 1
}' | http POST http://localhost:8812/uc-api/action Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/action', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
's': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0006144,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0452583,
"pending": 1559868829.0455182,
"refused": 1559868829.0458727
},
"uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
}
Parameters:
- k valid API key
- i unit id
Optionally:
- s desired unit status
- v desired unit value
- w wait for the completion for the specified number of seconds
- u action UUID (will be auto generated if none specified)
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
action_toggle - toggle unit status
Create unit control action to toggle its status (1->0, 0->1)
http
POST /uc-api/action_toggle HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/action_toggle -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/action_toggle --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/action_toggle Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/action_toggle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0010161,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.087297,
"pending": 1559868829.0876813,
"refused": 1559868829.088313
},
"uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
}
Parameters:
- k valid API key
- i unit id
Optionally:
- w wait for the completion for the specified number of seconds
- u action UUID (will be auto generated if none specified)
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
disable_actions - disable unit actions
Disables unit to run and queue new actions.
http
POST /uc-api/disable_actions HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/disable_actions -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/disable_actions --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/disable_actions Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/disable_actions', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
enable_actions - enable unit actions
Enables unit to run and queue new actions.
http
POST /uc-api/enable_actions HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/enable_actions -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/enable_actions --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/enable_actions Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/enable_actions', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
groups - get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
POST /uc-api/groups HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "p": "unit" }
curl
curl -i -X POST http://localhost:8812/uc-api/groups -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "unit"}'
wget
wget -S -O- http://localhost:8812/uc-api/groups --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "unit"}'
httpie
echo '{
"k": "mykey",
"p": "unit"
}' | http POST http://localhost:8812/uc-api/groups Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/groups', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'unit',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"room1",
"test_device_5",
"test_device_7",
"tests"
]
Parameters:
- k valid API key
- p item type (unit [U] or sensor [S])
kill - kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
http
POST /uc-api/kill HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/kill -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/kill --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/kill Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/kill', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
Returns:
If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)
q_clean - clean action queue of unit
Cancels all queued actions, keeps the current action running.
http
POST /uc-api/q_clean HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/q_clean -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/q_clean --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/q_clean Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/q_clean', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
result - get action status
Checks the result of the action by its UUID or returns the actions for the specified unit.
http
POST /uc-api/result HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/result -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/result --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/result Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/result', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0006144,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0452583,
"pending": 1559868829.0455182,
"refused": 1559868829.0458727
},
"uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
},
{
"err": "",
"exitcode": -15,
"finished": true,
"finished_in": 1.301712,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "terminated",
"time": {
"created": 1559868829.0540679,
"pending": 1559868829.054227,
"queued": 1559868829.05472,
"running": 1559868829.0551677,
"terminated": 1559868830.35578
},
"uuid": "18bcbf97-d35d-4f18-8354-d18d092df5f7"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0010161,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.087297,
"pending": 1559868829.0876813,
"refused": 1559868829.088313
},
"uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.000658,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0973055,
"pending": 1559868829.0975406,
"refused": 1559868829.0979636
},
"uuid": "17570e18-03ca-4772-8665-90af574325b9"
}
]
Parameters:
- k valid API key
Optionally:
- u action uuid or
- i unit id
- g filter by unit group
- s filter by action status: Q for queued, R for running, F for finished
Returns:
list or single serialized action object
start_item_maintenance - start item maintenance mode
During maintenance mode all item updates are ignored, however actions still can be executed
http
POST /uc-api/start_item_maintenance HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1" }
curl
curl -i -X POST http://localhost:8812/uc-api/start_item_maintenance -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/start_item_maintenance --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey"}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/start_item_maintenance Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/start_item_maintenance', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k masterkey
- i item ID
state - get item state
State of the item or all items of the specified type can be obtained using state command.
http
POST /uc-api/state HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "p": "sensor" }
curl
curl -i -X POST http://localhost:8812/uc-api/state -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "sensor"}'
wget
wget -S -O- http://localhost:8812/uc-api/state --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "sensor"}'
httpie
echo '{
"k": "mykey",
"p": "sensor"
}' | http POST http://localhost:8812/uc-api/state Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/state', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'sensor',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"full_id": "tests/sensor1",
"group": "tests",
"id": "sensor1",
"oid": "sensor:tests/sensor1",
"status": 1,
"type": "sensor",
"value": 29.445
},
{
"full_id": "tests/sensor2",
"group": "tests",
"id": "sensor2",
"oid": "sensor:tests/sensor2",
"status": 1,
"type": "sensor",
"value": 29.445
}
]
Parameters:
- k valid API key
- p item type (unit [U] or sensor [S])
Optionally:
- i item id
- g item group
- full return full state
state_history - get item state history
State history of one item or several items of the specified type can be obtained using state_history command.
http
POST /uc-api/state_history HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1" }
curl
curl -i -X POST http://localhost:8812/uc-api/state_history -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/state_history --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey"}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/state_history Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/state_history', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"status": [
null,
null,
1,
null,
1
],
"t": [
1552865635.6868849,
1552866234.5211835,
1552866297.7497892,
1552866495.7593722,
1552866511.8293397,
1552866513.8805466
],
"value": [
29.445,
29.42,
28,
29.11,
29.42,
29.441
]
}
Parameters:
- k valid API key
- a history notifier id (default: db_1)
- i item oids or full ids, list or comma separated
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
- g output format (“list”, “dict” or “chart”, default is “list”)
- c options for chart (dict or comma separated)
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
- type: chart type (line or bar, default is line)
- tf: chart time format
- out: output format (svg, png, default is svg),
- style: chart style (without “Style” suffix, e.g. Dark)
- other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
stop_item_maintenance - stop item maintenance mode
http
POST /uc-api/stop_item_maintenance HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1" }
curl
curl -i -X POST http://localhost:8812/uc-api/stop_item_maintenance -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/stop_item_maintenance --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey"}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/stop_item_maintenance Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/stop_item_maintenance', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k masterkey
- i item ID
terminate - terminate action execution
Terminates or cancel the action if it is still queued
http
POST /uc-api/terminate HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/terminate -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/terminate --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/terminate Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/terminate', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- u action uuid or
- i unit id
Returns:
An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)
update - update the status and value of the item
Updates the status and value of the item. This is one of the ways of passive state update, for example with the use of an external controller.
Note
Calling without s and v params will force item to perform passive update requesting its status from update script or driver.
http
POST /uc-api/update HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1", "s": 1, "v": 29.445 }
curl
curl -i -X POST http://localhost:8812/uc-api/update -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey", "s": 1, "v": 29.445}'
wget
wget -S -O- http://localhost:8812/uc-api/update --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey", "s": 1, "v": 29.445}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey",
"s": 1,
"v": 29.445
}' | http POST http://localhost:8812/uc-api/update Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/update', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
's': 1,
'v': 29.445,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i item id
Optionally:
- s item status
- v item value
Item management
list - list items
http
POST /uc-api/list HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "",
"full_id": "tests/sensor1",
"group": "tests",
"id": "sensor1",
"oid": "sensor:tests/sensor1",
"type": "sensor"
},
{
"description": "",
"full_id": "tests/sensor2",
"group": "tests",
"id": "sensor2",
"oid": "sensor:tests/sensor2",
"type": "sensor"
},
{
"description": "",
"full_id": "tests/unit1",
"group": "tests",
"id": "unit1",
"oid": "unit:tests/unit1",
"type": "unit"
},
{
"description": "",
"full_id": "tests/unit3",
"group": "tests",
"id": "unit3",
"oid": "unit:tests/unit3",
"type": "unit"
}
]
Parameters:
- k API key with master permissions
Optionally:
- p filter by item type
- g filter by item group
Returns:
the list of all item available
create - create new item
Creates new item.
http
POST /uc-api/create HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "sensor:tests/sensor1", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create -H 'Content-Type: application/json' --data-raw '{"i": "sensor:tests/sensor1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create --header='Content-Type: application/json' --post-data='{"i": "sensor:tests/sensor1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "sensor:tests/sensor1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:tests/sensor1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/sensor1",
"group": "tests",
"id": "sensor1",
"oid": "sensor:tests/sensor1",
"status": 0,
"type": "sensor",
"value": "null"
}
Parameters:
- k API key with master permissions
- i item oid (type:group/id)
Optionally:
- g item group
- save save multi-update configuration immediately
create_mu - create multi-update
Creates new multi-update.
http
POST /uc-api/create_mu HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mu:tests/mu1", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_mu -H 'Content-Type: application/json' --data-raw '{"i": "mu:tests/mu1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create_mu --header='Content-Type: application/json' --post-data='{"i": "mu:tests/mu1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "mu:tests/mu1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create_mu Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_mu', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mu:tests/mu1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/mu1",
"group": "tests",
"id": "mu1",
"oid": "mu:tests/mu1",
"status": 0,
"type": "mu",
"value": "null"
}
Parameters:
- k API key with master permissions
- i multi-update id
Optionally:
- g multi-update group
- save save multi-update configuration immediately
create_sensor - create new sensor
Creates new sensor.
http
POST /uc-api/create_sensor HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "tests/sensor5", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_sensor -H 'Content-Type: application/json' --data-raw '{"i": "tests/sensor5", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create_sensor --header='Content-Type: application/json' --post-data='{"i": "tests/sensor5", "k": "mykey", "save": true}'
httpie
echo '{
"i": "tests/sensor5",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create_sensor Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_sensor', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/sensor5',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/sensor5",
"group": "tests",
"id": "sensor5",
"oid": "sensor:tests/sensor5",
"status": 0,
"type": "sensor",
"value": "null"
}
Parameters:
- k API key with master permissions
- i sensor id
Optionally:
- g sensor group
- save save sensor configuration immediately
create_unit - create new unit
Creates new unit.
http
POST /uc-api/create_unit HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "tests/unit1", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_unit -H 'Content-Type: application/json' --data-raw '{"i": "tests/unit1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/create_unit --header='Content-Type: application/json' --post-data='{"i": "tests/unit1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "tests/unit1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/uc-api/create_unit Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_unit', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/unit1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": false,
"full_id": "tests/unit1",
"group": "tests",
"id": "unit1",
"nstatus": 0,
"nvalue": "null",
"oid": "unit:tests/unit1",
"status": 0,
"type": "unit",
"value": "null"
}
Parameters:
- k API key with master permissions
- i unit id
Optionally:
- g unit group
- save save unit configuration immediately
destroy - delete item or group
Deletes the item or the group (and all the items in it) from the system.
http
POST /uc-api/destroy HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/destroy -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/destroy --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/destroy Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/destroy', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- g group (either item or group must be specified)
get_config - get item configuration
http
POST /uc-api/get_config HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_config -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_config --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_config Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_config', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/unit1",
"group": "tests",
"id": "unit1",
"oid": "unit:tests/unit1",
"type": "unit"
}
Parameters:
- k API key with master permissions
- i item id
Returns:
complete item configuration
list_props - list item properties
Get all editable parameters of the item confiugration.
http
POST /uc-api/list_props HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_props -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_props --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_props Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_allow_termination": false,
"action_always_exec": false,
"action_driver_config": null,
"action_enabled": true,
"action_exec": null,
"action_queue": 0,
"action_timeout": null,
"auto_off": 0,
"description": "",
"expires": 0,
"location": null,
"mqtt_control": null,
"mqtt_update": null,
"snmp_trap": null,
"status_labels": {
"0": "OFF",
"1": "ON"
},
"term_kill_interval": null,
"update_delay": 0,
"update_driver_config": null,
"update_exec": null,
"update_exec_after_action": false,
"update_if_action": false,
"update_interval": 0,
"update_state_after_action": true,
"update_timeout": null,
"virtual": false
}
Parameters:
- k API key with master permissions
- i item id
save_config - save item configuration
Saves item. configuration on disk (even if it hasn’t been changed)
http
POST /uc-api/save_config HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/save_config -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/save_config --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/save_config Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/save_config', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
set_prop - set item property
Set configuration parameters of the item.
http
POST /uc-api/set_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "p": "action_allow_termination", "v": true }
curl
curl -i -X POST http://localhost:8812/uc-api/set_prop -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "p": "action_allow_termination", "v": true}'
wget
wget -S -O- http://localhost:8812/uc-api/set_prop --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "p": "action_allow_termination", "v": true}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"p": "action_allow_termination",
"v": true
}' | http POST http://localhost:8812/uc-api/set_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/set_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
'p': 'action_allow_termination',
'v': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
clone - clone item
Creates a copy of the item.
http
POST /uc-api/clone HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "n": "unit:tests/clone_of_unit1" }
curl
curl -i -X POST http://localhost:8812/uc-api/clone -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "n": "unit:tests/clone_of_unit1"}'
wget
wget -S -O- http://localhost:8812/uc-api/clone --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "n": "unit:tests/clone_of_unit1"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"n": "unit:tests/clone_of_unit1"
}' | http POST http://localhost:8812/uc-api/clone Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/clone', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
'n': 'unit:tests/clone_of_unit1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/clone_of_unit1",
"group": "tests",
"id": "clone_of_unit1",
"nstatus": 0,
"nvalue": "null",
"oid": "unit:tests/clone_of_unit1",
"status": 0,
"type": "unit",
"value": "null"
}
Parameters:
- k API key with master permissions
- i item id
- n new item id
Optionally:
- g group for new item
- save save multi-update configuration immediately
clone_group - clone group
Creates a copy of all items from the group.
http
POST /uc-api/clone_group HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "g": "tests", "n": "clone_of_tests" }
curl
curl -i -X POST http://localhost:8812/uc-api/clone_group -H 'Content-Type: application/json' --data-raw '{"g": "tests", "k": "mykey", "n": "clone_of_tests"}'
wget
wget -S -O- http://localhost:8812/uc-api/clone_group --header='Content-Type: application/json' --post-data='{"g": "tests", "k": "mykey", "n": "clone_of_tests"}'
httpie
echo '{
"g": "tests",
"k": "mykey",
"n": "clone_of_tests"
}' | http POST http://localhost:8812/uc-api/clone_group Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/clone_group', headers={
'Content-Type': 'application/json',
}, json={
'g': 'tests',
'k': 'mykey',
'n': 'clone_of_tests',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- g group to clone
- n new group to clone to
Optionally:
- p item ID prefix, e.g. device1. for device1.temp1, device1.fan1
- r iem ID prefix in the new group, e.g. device2 (both prefixes must be specified)
- save save configuration immediately
1-Wire bus via OWFS
create_owfs_bus - create OWFS bus
Creates (defines) OWFS bus with the specified configuration.
Parameter “location” (“n”) should contain the connection configuration, e.g. “localhost:4304” for owhttpd or “i2c=/dev/i2c-1:ALL”, “/dev/i2c-0 –w1” for local 1-Wire bus via I2C, depending on type.
http
POST /uc-api/create_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local", "n": "localhost:4304", "l": true, "t": 1, "r": 5, "d": 0.3, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_owfs_bus -H 'Content-Type: application/json' --data-raw '{"d": 0.3, "i": "bus_local", "k": "mykey", "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/create_owfs_bus --header='Content-Type: application/json' --post-data='{"d": 0.3, "i": "bus_local", "k": "mykey", "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'
httpie
echo '{
"d": 0.3,
"i": "bus_local",
"k": "mykey",
"l": true,
"n": "localhost:4304",
"r": 5,
"save": true,
"t": 1
}' | http POST http://localhost:8812/uc-api/create_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'd': 0.3,
'i': 'bus_local',
'k': 'mykey',
'l': True,
'n': 'localhost:4304',
'r': 5,
'save': True,
't': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i bus ID which will be used later in PHI configurations, required
- n OWFS location
Optionally:
- l lock port on operations, which means to wait while OWFS bus is used by other controller thread (driver command)
- t OWFS operations timeout (in seconds, default: default timeout)
- r retry attempts for each operation (default: no retries)
- d delay between bus operations (default: 50ms)
- save save OWFS bus config after creation
Returns:
If bus with the selected ID is already defined, error is not returned and bus is recreated.
destroy_owfs_bus - delete OWFS bus
Deletes (undefines) OWFS bus.
Note
In some cases deleted OWFS bus located on I2C may lock libow library calls, which require controller restart until you can use (create) the same I2C bus again.
http
POST /uc-api/destroy_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/destroy_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/destroy_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/destroy_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/destroy_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i bus ID
get_owfs_bus - get OWFS bus configuration
http
POST /uc-api/get_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.3,
"id": "bus_local",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
}
Parameters:
- k API key with master permissions
- i bus ID
list_owfs_buses - list OWFS buses
http
POST /uc-api/list_owfs_buses HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_owfs_buses -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_owfs_buses --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_owfs_buses Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_owfs_buses', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"delay": 0.3,
"id": "bus1",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
},
{
"delay": 0.3,
"id": "bus_local",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
},
{
"delay": 0.05,
"id": "bus_local1",
"location": "localhost:4304",
"lock": false,
"retries": 0,
"timeout": 4.0
},
{
"delay": 0.05,
"id": "test",
"location": "localhost:4304",
"lock": true,
"retries": 0,
"timeout": 4.0
}
]
Parameters:
- k API key with master permissions
scan_owfs_bus - scan OWFS bus
Scan OWFS bus for connected 1-Wire devices.
http
POST /uc-api/scan_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/scan_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/scan_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/scan_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/scan_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"path": "22.765A2E63339F",
"type": "DS1822"
},
{
"path": "28.4AEC29CDBAAB",
"type": "DS18B20"
},
{
"path": "10.67C6697351FF",
"type": "DS18S20"
},
{
"path": "05.F2FBE3467CC2",
"type": "DS2405"
},
{
"path": "29.54F81BE8E78D",
"type": "DS2408"
}
]
Parameters:
- k API key with master permissions
- i bus ID
Optionally:
- p specified equipment type (e.g. DS18S20,DS2405), list or comma separated
- a Equipment attributes (e.g. temperature, PIO), list comma separated
- n Equipment path
- has_all Equipment should have all specified attributes
- full obtain all attributes plus values
Returns:
If both “a” and “full” args are specified. the function will examine and values of attributes specified in “a” param. (This will poll “released” bus, even if locking is set up, so be careful with this feature in production environment).
Bus acquire error can be caused in 2 cases:
- bus is locked * owfs resource not initialized (libow or location problem)
test_owfs_bus - test OWFS bus
Verifies OWFS bus checking library initialization status.
http
POST /uc-api/test_owfs_bus HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "bus_local" }
curl
curl -i -X POST http://localhost:8812/uc-api/test_owfs_bus -H 'Content-Type: application/json' --data-raw '{"i": "bus_local", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test_owfs_bus --header='Content-Type: application/json' --post-data='{"i": "bus_local", "k": "mykey"}'
httpie
echo '{
"i": "bus_local",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test_owfs_bus Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test_owfs_bus', headers={
'Content-Type': 'application/json',
}, json={
'i': 'bus_local',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i bus ID
Modbus ports
create_modbus_port - create virtual Modbus port
Creates virtual Modbus port with the specified configuration.
Modbus params should contain the configuration of hardware Modbus port. The following hardware port types are supported:
- tcp , udp Modbus protocol implementations for TCP/IP networks. The params should be specified as: <protocol>:<host>[:port], e.g. tcp:192.168.11.11:502
- rtu, ascii, binary Modbus protocol implementations for the local bus connected with USB or serial port. The params should be specified as: <protocol>:<device>:<speed>:<data>:<parity>:<stop> e.g. rtu:/dev/ttyS0:9600:8:E:1
http
POST /uc-api/create_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1", "p": "udp:192.168.33.33:502", "l": true, "t": 0.5, "r": 3, "d": 0.2, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/create_modbus_port -H 'Content-Type: application/json' --data-raw '{"d": 0.2, "i": "mbp1", "k": "mykey", "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'
wget
wget -S -O- http://localhost:8812/uc-api/create_modbus_port --header='Content-Type: application/json' --post-data='{"d": 0.2, "i": "mbp1", "k": "mykey", "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'
httpie
echo '{
"d": 0.2,
"i": "mbp1",
"k": "mykey",
"l": true,
"p": "udp:192.168.33.33:502",
"r": 3,
"save": true,
"t": 0.5
}' | http POST http://localhost:8812/uc-api/create_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/create_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'd': 0.2,
'i': 'mbp1',
'k': 'mykey',
'l': True,
'p': 'udp:192.168.33.33:502',
'r': 3,
'save': True,
't': 0.5,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i virtual port ID which will be used later in PHI configurations, required
- p Modbus params
Optionally:
- l lock port on operations, which means to wait while Modbus port is used by other controller thread (driver command)
- t Modbus operations timeout (in seconds, default: default timeout)
- r retry attempts for each operation (default: no retries)
- d delay between virtual port operations (default: 20ms)
- save save Modbus port config after creation
Returns:
If port with the selected ID is already created, error is not returned and port is recreated.
destroy_modbus_port - delete virtual Modbus port
Deletes virtual Modbus port.
http
POST /uc-api/destroy_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1" }
curl
curl -i -X POST http://localhost:8812/uc-api/destroy_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "mbp1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/destroy_modbus_port --header='Content-Type: application/json' --post-data='{"i": "mbp1", "k": "mykey"}'
httpie
echo '{
"i": "mbp1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/destroy_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/destroy_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mbp1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i virtual port ID
get_modbus_port - get virtual Modbus port configuration
http
POST /uc-api/get_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "mbp1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_modbus_port --header='Content-Type: application/json' --post-data='{"i": "mbp1", "k": "mykey"}'
httpie
echo '{
"i": "mbp1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mbp1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.2,
"id": "mbp1",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
}
Parameters:
- k API key with master permissions
- i port ID
list_modbus_ports - list virtual Modbus ports
http
POST /uc-api/list_modbus_ports HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_modbus_ports -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_modbus_ports --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_modbus_ports Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_modbus_ports', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"delay": 0.2,
"id": "mbp1",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
},
{
"delay": 0.2,
"id": "mbp2",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
},
{
"delay": 0.02,
"id": "test",
"lock": false,
"params": "tcp:192.168.1.1",
"retries": 0,
"timeout": 4.0
}
]
Parameters:
- k API key with master permissions
- i virtual port ID
read_modbus_port - read Modbus register(s) from remote slave
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).
Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15
http
POST /uc-api/read_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "h10-12,c5-6", "p": "local", "s": 1 }
curl
curl -i -X POST http://localhost:8812/uc-api/read_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "h10-12,c5-6", "k": "mykey", "p": "local", "s": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/read_modbus_port --header='Content-Type: application/json' --post-data='{"i": "h10-12,c5-6", "k": "mykey", "p": "local", "s": 1}'
httpie
echo '{
"i": "h10-12,c5-6",
"k": "mykey",
"p": "local",
"s": 1
}' | http POST http://localhost:8812/uc-api/read_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/read_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'h10-12,c5-6',
'k': 'mykey',
'p': 'local',
's': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"addr": "c5",
"value": 0
},
{
"addr": "c6",
"value": 0
},
{
"addr": "h10",
"value": 25
},
{
"addr": "h11",
"value": 0
},
{
"addr": "h12",
"value": 0
}
]
Parameters:
- k API key with master permissions
- p Modbus virtual port
- s Slave ID
- i Modbus register(s)
Optionally:
- t max allowed timeout for the operation
test_modbus_port - test virtual Modbus port
Verifies virtual Modbus port by calling connect() Modbus client method.
Note
As Modbus UDP doesn’t require a port to be connected, API call always returns success unless the port is locked.
http
POST /uc-api/test_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "mbp1" }
curl
curl -i -X POST http://localhost:8812/uc-api/test_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "mbp1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test_modbus_port --header='Content-Type: application/json' --post-data='{"i": "mbp1", "k": "mykey"}'
httpie
echo '{
"i": "mbp1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'mbp1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i virtual port ID
write_modbus_port - write Modbus register(s) to remote slave
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, c - coil).
http
POST /uc-api/write_modbus_port HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "h10", "p": "local", "s": 1, "v": 2522 }
curl
curl -i -X POST http://localhost:8812/uc-api/write_modbus_port -H 'Content-Type: application/json' --data-raw '{"i": "h10", "k": "mykey", "p": "local", "s": 1, "v": 2522}'
wget
wget -S -O- http://localhost:8812/uc-api/write_modbus_port --header='Content-Type: application/json' --post-data='{"i": "h10", "k": "mykey", "p": "local", "s": 1, "v": 2522}'
httpie
echo '{
"i": "h10",
"k": "mykey",
"p": "local",
"s": 1,
"v": 2522
}' | http POST http://localhost:8812/uc-api/write_modbus_port Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/write_modbus_port', headers={
'Content-Type': 'application/json',
}, json={
'i': 'h10',
'k': 'mykey',
'p': 'local',
's': 1,
'v': 2522,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- p Modbus virtual port
- s Slave ID
- i Modbus register address
- v register value(s) (integer or hex or list)
Optionally:
- t max allowed timeout for the operation
get_modbus_slave_data - get Modbus slave data
Get data from Modbus slave memory space
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).
Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15
http
POST /uc-api/get_modbus_slave_data HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "h1000-1005,c10-15" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_modbus_slave_data -H 'Content-Type: application/json' --data-raw '{"i": "h1000-1005,c10-15", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_modbus_slave_data --header='Content-Type: application/json' --post-data='{"i": "h1000-1005,c10-15", "k": "mykey"}'
httpie
echo '{
"i": "h1000-1005,c10-15",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_modbus_slave_data Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_modbus_slave_data', headers={
'Content-Type': 'application/json',
}, json={
'i': 'h1000-1005,c10-15',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"addr": "c10",
"value": 0
},
{
"addr": "c11",
"value": 0
},
{
"addr": "c12",
"value": 0
},
{
"addr": "c13",
"value": 0
},
{
"addr": "c14",
"value": 0
},
{
"addr": "c15",
"value": 0
},
{
"addr": "h1000",
"value": 0
},
{
"addr": "h1001",
"value": 0
},
{
"addr": "h1002",
"value": 0
},
{
"addr": "h1003",
"value": 0
},
{
"addr": "h1004",
"value": 0
},
{
"addr": "h1005",
"value": 0
}
]
Parameters:
- k API key with master permissions
- i Modbus register(s)
Physical interfaces (PHIs)
exec_phi - execute additional PHI commands
Execute PHI command and return execution result (as-is). help command returns all available commands.
http
POST /uc-api/exec_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "c": "update_firmware", "a": "/opt/firmware/fw.dat" }
curl
curl -i -X POST http://localhost:8812/uc-api/exec_phi -H 'Content-Type: application/json' --data-raw '{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/exec_phi --header='Content-Type: application/json' --post-data='{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "i": "test1", "k": "mykey"}'
httpie
echo '{
"a": "/opt/firmware/fw.dat",
"c": "update_firmware",
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/exec_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/exec_phi', headers={
'Content-Type': 'application/json',
}, json={
'a': '/opt/firmware/fw.dat',
'c': 'update_firmware',
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"output": "not implemented"
}
Parameters:
- k API key with master permissions
- i PHI id
- c command to exec
- a command argument
get_phi_ports - get list of PHI ports
http
POST /uc-api/get_phi_ports HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_phi_ports -H 'Content-Type: application/json' --data-raw '{"i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_phi_ports --header='Content-Type: application/json' --post-data='{"i": "test1", "k": "mykey"}'
httpie
echo '{
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_phi_ports Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_phi_ports', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "virtual relay port #1",
"name": "port #1",
"port": "1"
},
{
"description": "virtual relay port #2",
"name": "port #2",
"port": "2"
},
{
"description": "virtual relay port #3",
"name": "port #3",
"port": "3"
},
{
"description": "virtual relay port #4",
"name": "port #4",
"port": "4"
},
{
"description": "virtual relay port #5",
"name": "port #5",
"port": "5"
},
{
"description": "virtual relay port #6",
"name": "port #6",
"port": "6"
},
{
"description": "virtual relay port #7",
"name": "port #7",
"port": "7"
},
{
"description": "virtual relay port #8",
"name": "port #8",
"port": "8"
},
{
"description": "virtual relay port #9",
"name": "port #9",
"port": "9"
},
{
"description": "virtual relay port #10",
"name": "port #10",
"port": "10"
},
{
"description": "virtual relay port #11",
"name": "port #11",
"port": "11"
},
{
"description": "virtual relay port #12",
"name": "port #12",
"port": "12"
},
{
"description": "virtual relay port #13",
"name": "port #13",
"port": "13"
},
{
"description": "virtual relay port #14",
"name": "port #14",
"port": "14"
},
{
"description": "virtual relay port #15",
"name": "port #15",
"port": "15"
},
{
"description": "virtual relay port #16",
"name": "port #16",
"port": "16"
}
]
Parameters:
- k API key with master permissions
- i PHI id
list_phi - list loaded PHIs
http
POST /uc-api/list_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_phi -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_phi --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_phi', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"id": "test",
"mod": "vrtrelay"
},
{
"id": "test1",
"mod": "vrtrelay"
},
{
"id": "test2",
"mod": "vrtrelay"
}
]
Parameters:
- k API key with master permissions
- full get exntended information
list_phi_mods - get list of available PHI modules
http
POST /uc-api/list_phi_mods HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_phi_mods -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_phi_mods --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_phi_mods Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_phi_mods', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "EG-PM2-LAN smart PDU",
"equipment": [
"EG-PM2-LAN"
],
"features": [
"aao_get",
"port_set",
"cache"
],
"help": "\nPHI for Energenie (Gembird) EG-PM2-LAN smart PDU. You may use 'skip_logout'\nparam to let PHI skip logout procedure after the requests. This speed up the\nfunctions however may cause the equipment to be locked to UC IP only.\n",
"id": null,
"license": "https://www.eva-ics.com/license",
"lpi_default": "basic",
"mod": "eg_pm2lan",
"mods_required": [],
"oid": null,
"required": [
"aao_get",
"port_set",
"status",
"action"
],
"version": "1.0.2"
},
{
"api": 3,
"author": "Altertech Group, https://www.altertech.com/",
"description": "1-Wire OWFS universal sensor driver",
"equipment": [
"Any 1-Wire sensor"
],
"features": [
"port_get",
"universal"
],
"help": "\nPHI for Maxim Integrated 1-Wire DS18N20 equipment working via OWFS.\n\nCan be used for various types of sensors as attr (e.g. \"temperature\" or\n\"voltage\") is specified by user. This is unversal PHI, owfs bus, path and attr\ncan be specified in EVA ICS sensor configuration.\n",
"id": null,
"license": "Apache License 2.0",
"lpi_default": "sensor",
"mod": "ow_sensor",
"mods_required": [],
"oid": null,
"required": [
"port_get",
"value"
],
"version": "1.0.0"
}
]
Parameters:
- k API key with master permissions
load_phi - load PHI module
Loads Physical Interface.
http
POST /uc-api/load_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "m": "vrtrelay", "c": "default_status=0", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/load_phi -H 'Content-Type: application/json' --data-raw '{"c": "default_status=0", "i": "test1", "k": "mykey", "m": "vrtrelay", "save": true}'
wget
wget -S -O- http://localhost:8812/uc-api/load_phi --header='Content-Type: application/json' --post-data='{"c": "default_status=0", "i": "test1", "k": "mykey", "m": "vrtrelay", "save": true}'
httpie
echo '{
"c": "default_status=0",
"i": "test1",
"k": "mykey",
"m": "vrtrelay",
"save": true
}' | http POST http://localhost:8812/uc-api/load_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/load_phi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'default_status=0',
'i': 'test1',
'k': 'mykey',
'm': 'vrtrelay',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 0
},
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"id": "test1",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test1",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
}
Parameters:
- k API key with master permissions
- i PHI ID
- m PHI module
Optionally:
- c PHI configuration
- save save driver configuration after successful call
modhelp_phi - get PHI usage help
http
POST /uc-api/modhelp_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "vrtrelay", "c": "cfg" }
curl
curl -i -X POST http://localhost:8812/uc-api/modhelp_phi -H 'Content-Type: application/json' --data-raw '{"c": "cfg", "k": "mykey", "m": "vrtrelay"}'
wget
wget -S -O- http://localhost:8812/uc-api/modhelp_phi --header='Content-Type: application/json' --post-data='{"c": "cfg", "k": "mykey", "m": "vrtrelay"}'
httpie
echo '{
"c": "cfg",
"k": "mykey",
"m": "vrtrelay"
}' | http POST http://localhost:8812/uc-api/modhelp_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modhelp_phi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'cfg',
'k': 'mykey',
'm': 'vrtrelay',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"help": "ports status on load (default: -1)",
"name": "default_status",
"required": false,
"type": "int"
},
{
"help": "send updates to items every N sec",
"name": "update",
"required": false,
"type": "float"
}
]
Parameters:
- k API key with master permissions
- m PHI module name (without .py extension)
- c help context (cfg, get or set)
modinfo_phi - get PHI module info
http
POST /uc-api/modinfo_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "vrtrelay" }
curl
curl -i -X POST http://localhost:8812/uc-api/modinfo_phi -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "vrtrelay"}'
wget
wget -S -O- http://localhost:8812/uc-api/modinfo_phi --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "vrtrelay"}'
httpie
echo '{
"k": "mykey",
"m": "vrtrelay"
}' | http POST http://localhost:8812/uc-api/modinfo_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modinfo_phi', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'vrtrelay',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": null,
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
}
Parameters:
- k API key with master permissions
- m PHI module name (without .py extension)
phi_discover - discover installed equipment supported by PHI module
http
POST /uc-api/phi_discover HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "nanoleaf" }
curl
curl -i -X POST http://localhost:8812/uc-api/phi_discover -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "nanoleaf"}'
wget
wget -S -O- http://localhost:8812/uc-api/phi_discover --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "nanoleaf"}'
httpie
echo '{
"k": "mykey",
"m": "nanoleaf"
}' | http POST http://localhost:8812/uc-api/phi_discover Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/phi_discover', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'nanoleaf',
})
response
HTTP/1.1 200 OK
Content-Type: application/json
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Length: 411
[
{
"!opt": "cols",
"value": [
"IP",
"Name"
]
},
{
"!load": {
"host": "192.168.25.81"
},
"IP": "192.168.25.81",
"Name": "Nanoleaf Light Panels 54:e2:31"
},
{
"!load": {
"host": "10.90.1.82"
},
"IP": "10.90.1.82",
"Name": "Nanoleaf Light Panels 54:f2:36"
}
]
Parameters:
- k API key with master permissions
- m PHI module name (without .py extension)
Optionally:
- x interface to perform discover on
- w max time for the operation
put_phi_mod - upload PHI module
Allows to upload new PHI module to xc/drivers/phi folder.
http
POST /uc-api/put_phi_mod HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "gpio_button", "c": "<MODULE_CONTENT>" }
curl
curl -i -X POST http://localhost:8812/uc-api/put_phi_mod -H 'Content-Type: application/json' --data-raw '{"c": "<MODULE_CONTENT>", "k": "mykey", "m": "gpio_button"}'
wget
wget -S -O- http://localhost:8812/uc-api/put_phi_mod --header='Content-Type: application/json' --post-data='{"c": "<MODULE_CONTENT>", "k": "mykey", "m": "gpio_button"}'
httpie
echo '{
"c": "<MODULE_CONTENT>",
"k": "mykey",
"m": "gpio_button"
}' | http POST http://localhost:8812/uc-api/put_phi_mod Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/put_phi_mod', headers={
'Content-Type': 'application/json',
}, json={
'c': '<MODULE_CONTENT>',
'k': 'mykey',
'm': 'gpio_button',
})
response
HTTP/1.1 200 OK
Content-Type: application/json
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "GPIO buttons",
"equipment": [
"GPIO buttons"
],
"features": [
"events"
],
"help": " Handling pressed events from GPIO buttons.\n\nPHI doesn't provide any control/monitoring functions, each button can be\nconfigured as unit (via basic LPI) or sensor (via sensor) and contain its port\nin update_driver_config, update_interval should be set to 0.\n",
"license": "Apache License 2.0",
"lpi_default": "sensor",
"mod": "gpio_button",
"mods_required": [
"gpiozero"
],
"oid": null,
"required": [],
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- m PHI module name (without .py extension)
- c module content
Optionally:
- force overwrite PHI module file if exists
set_phi_prop - set PHI configuration property
appends property to PHI configuration and reloads module
http
POST /uc-api/set_phi_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "p": "default_status", "v": 1, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/set_phi_prop -H 'Content-Type: application/json' --data-raw '{"i": "test1", "k": "mykey", "p": "default_status", "save": true, "v": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/set_phi_prop --header='Content-Type: application/json' --post-data='{"i": "test1", "k": "mykey", "p": "default_status", "save": true, "v": 1}'
httpie
echo '{
"i": "test1",
"k": "mykey",
"p": "default_status",
"save": true,
"v": 1
}' | http POST http://localhost:8812/uc-api/set_phi_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/set_phi_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1',
'k': 'mykey',
'p': 'default_status',
'save': True,
'v': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i PHI ID
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
test_phi - test PHI
Get PHI test result (as-is). All PHIs respond to self command, help command returns all available test commands.
http
POST /uc-api/test_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1", "c": "self" }
curl
curl -i -X POST http://localhost:8812/uc-api/test_phi -H 'Content-Type: application/json' --data-raw '{"c": "self", "i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/test_phi --header='Content-Type: application/json' --post-data='{"c": "self", "i": "test1", "k": "mykey"}'
httpie
echo '{
"c": "self",
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/test_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/test_phi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'self',
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"output": "OK"
}
Parameters:
- k API key with master permissions
- m PHI id
- c test command
unlink_phi_mod - delete PHI module file
Deletes PHI module file, if the module is loaded, all its instances should be unloaded first.
http
POST /uc-api/unlink_phi_mod HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "gpio_button" }
curl
curl -i -X POST http://localhost:8812/uc-api/unlink_phi_mod -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "gpio_button"}'
wget
wget -S -O- http://localhost:8812/uc-api/unlink_phi_mod --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "gpio_button"}'
httpie
echo '{
"k": "mykey",
"m": "gpio_button"
}' | http POST http://localhost:8812/uc-api/unlink_phi_mod Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/unlink_phi_mod', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'gpio_button',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- m PHI module name (without .py extension)
unload_phi - unload PHI
Unloads PHI. PHI should not be used by any driver (except default, but the driver should not be in use by any item).
If driver <phi_id.default> (which’s loaded automatically with PHI) is present, it will be unloaded as well.
http
POST /uc-api/unload_phi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1" }
curl
curl -i -X POST http://localhost:8812/uc-api/unload_phi -H 'Content-Type: application/json' --data-raw '{"i": "test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/unload_phi --header='Content-Type: application/json' --post-data='{"i": "test1", "k": "mykey"}'
httpie
echo '{
"i": "test1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/unload_phi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/unload_phi', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i PHI ID
LPI and drivers
assign_driver - assign driver to item
Sets the specified driver to item, automatically updating item props:
- action_driver_config,**update_driver_config** to the specified configuration * action_exec, update_exec to do all operations via driver function calls (sets both to |<driver_id>)
To unassign driver, set driver ID to empty/null.
http
POST /uc-api/assign_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "d": "test1.my", "c": "port=5" }
curl
curl -i -X POST http://localhost:8812/uc-api/assign_driver -H 'Content-Type: application/json' --data-raw '{"c": "port=5", "d": "test1.my", "i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/assign_driver --header='Content-Type: application/json' --post-data='{"c": "port=5", "d": "test1.my", "i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"c": "port=5",
"d": "test1.my",
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/assign_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/assign_driver', headers={
'Content-Type': 'application/json',
}, json={
'c': 'port=5',
'd': 'test1.my',
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k masterkey
- i item ID
- d driver ID (if none - all above item props are set to null)
- c configuration (e.g. port number)
Optionally:
- save save item configuration after successful call
get_driver - get loaded driver information
http
POST /uc-api/get_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1.my" }
curl
curl -i -X POST http://localhost:8812/uc-api/get_driver -H 'Content-Type: application/json' --data-raw '{"i": "test1.my", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/get_driver --header='Content-Type: application/json' --post-data='{"i": "test1.my", "k": "mykey"}'
httpie
echo '{
"i": "test1.my",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/get_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/get_driver', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1.my',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {},
"connections": {
"dport": "destination",
"port": "power"
},
"description": "Multistep LPI (opener)",
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration. Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
"id": "test1.my",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"lpi_id": "my",
"mod": "multistep",
"oid": "driver:uc/mws1-v1/test1.my",
"phi": {
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 1
},
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"id": "test1",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test1",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
},
"phi_id": "test1",
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- i PHI ID
list_drivers - list loaded drivers
http
POST /uc-api/list_drivers HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_drivers -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_drivers --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_drivers Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_drivers', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"id": "test.bose",
"lpi_id": "bose",
"mod": "multistep",
"phi_id": "test"
},
{
"features": [
"status",
"status_mp",
"mu_status",
"mu_status_mp",
"port_get",
"aao_get",
"action",
"action_mp",
"port_set",
"aao_set",
"events"
],
"id": "test.default",
"lpi_id": "default",
"mod": "basic",
"phi_id": "test"
}
]
Parameters:
- k API key with master permissions
- full get exntended information
list_lpi_mods - get list of available LPI modules
http
POST /uc-api/list_lpi_mods HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_lpi_mods -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_lpi_mods --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_lpi_mods Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_lpi_mods', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"connections": {
"port": "primary"
},
"description": "Basic LPI for simple devices",
"features": [
"status",
"status_mp",
"mu_status",
"mu_status_mp",
"port_get",
"aao_get",
"action",
"action_mp",
"port_set",
"aao_set",
"events"
],
"help": "\nBasic LPI for simple unit status control (on/off) and monitoring. Support\nstatus 0 and 1. Unit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port' i.e. to\n'socket' for a more fancy unit configuration. Each port may be specified as a\nsingle value or contain an array of values, in this case multiple ports are\nused simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state.\n",
"id": null,
"license": "Apache License 2.0",
"logic": "basic status on/off",
"lpi_id": null,
"mod": "basic",
"oid": null,
"phi_id": null,
"version": "1.0.0"
}
]
Parameters:
- k API key with master permissions
load_driver - load a driver
Loads a driver, combining previously loaded PHI and chosen LPI module.
http
POST /uc-api/load_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "my", "m": "multistep", "p": "test1" }
curl
curl -i -X POST http://localhost:8812/uc-api/load_driver -H 'Content-Type: application/json' --data-raw '{"i": "my", "k": "mykey", "m": "multistep", "p": "test1"}'
wget
wget -S -O- http://localhost:8812/uc-api/load_driver --header='Content-Type: application/json' --post-data='{"i": "my", "k": "mykey", "m": "multistep", "p": "test1"}'
httpie
echo '{
"i": "my",
"k": "mykey",
"m": "multistep",
"p": "test1"
}' | http POST http://localhost:8812/uc-api/load_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/load_driver', headers={
'Content-Type': 'application/json',
}, json={
'i': 'my',
'k': 'mykey',
'm': 'multistep',
'p': 'test1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {},
"connections": {
"dport": "destination",
"port": "power"
},
"description": "Multistep LPI (opener)",
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration. Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
"id": "test1.my",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"lpi_id": "my",
"mod": "multistep",
"oid": "driver:uc/mws1-v1/test1.my",
"phi": {
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 0
},
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"id": "test1",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test1",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
},
"phi_id": "test1",
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- i LPI ID
- m LPI module
- p PHI ID
Optionally:
- c Driver (LPI) configuration, optional
- save save configuration after successful call
modhelp_lpi - get LPI usage help
http
POST /uc-api/modhelp_lpi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "multistep", "c": "cfg" }
curl
curl -i -X POST http://localhost:8812/uc-api/modhelp_lpi -H 'Content-Type: application/json' --data-raw '{"c": "cfg", "k": "mykey", "m": "multistep"}'
wget
wget -S -O- http://localhost:8812/uc-api/modhelp_lpi --header='Content-Type: application/json' --post-data='{"c": "cfg", "k": "mykey", "m": "multistep"}'
httpie
echo '{
"c": "cfg",
"k": "mykey",
"m": "multistep"
}' | http POST http://localhost:8812/uc-api/modhelp_lpi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modhelp_lpi', headers={
'Content-Type': 'application/json',
}, json={
'c': 'cfg',
'k': 'mykey',
'm': 'multistep',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"help": "allow action even if current status is error",
"name": "bose",
"required": false,
"type": "bool"
}
]
Parameters:
- k API key with master permissions
- m LPI module name (without .py extension)
- c help context (cfg, action or update)
modinfo_lpi - get LPI module info
http
POST /uc-api/modinfo_lpi HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "multistep" }
curl
curl -i -X POST http://localhost:8812/uc-api/modinfo_lpi -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "multistep"}'
wget
wget -S -O- http://localhost:8812/uc-api/modinfo_lpi --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "multistep"}'
httpie
echo '{
"k": "mykey",
"m": "multistep"
}' | http POST http://localhost:8812/uc-api/modinfo_lpi Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/modinfo_lpi', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'multistep',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"connections": {
"dport": "destination",
"port": "power"
},
"description": "Multistep LPI (opener)",
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration. Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"mod": "multistep",
"oid": null,
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- m LPI module name (without .py extension)
set_driver_prop - set driver (LPI) configuration property
appends property to LPI configuration and reloads module
http
POST /uc-api/set_driver_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1.my", "p": "bose", "v": 1, "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/set_driver_prop -H 'Content-Type: application/json' --data-raw '{"i": "test1.my", "k": "mykey", "p": "bose", "save": true, "v": 1}'
wget
wget -S -O- http://localhost:8812/uc-api/set_driver_prop --header='Content-Type: application/json' --post-data='{"i": "test1.my", "k": "mykey", "p": "bose", "save": true, "v": 1}'
httpie
echo '{
"i": "test1.my",
"k": "mykey",
"p": "bose",
"save": true,
"v": 1
}' | http POST http://localhost:8812/uc-api/set_driver_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/set_driver_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1.my',
'k': 'mykey',
'p': 'bose',
'save': True,
'v': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i driver ID
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save driver configuration after successful call
unload_driver - unload driver
Unloads driver. Driver should not be used by any item.
http
POST /uc-api/unload_driver HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test1.my" }
curl
curl -i -X POST http://localhost:8812/uc-api/unload_driver -H 'Content-Type: application/json' --data-raw '{"i": "test1.my", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/unload_driver --header='Content-Type: application/json' --post-data='{"i": "test1.my", "k": "mykey"}'
httpie
echo '{
"i": "test1.my",
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/unload_driver Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/unload_driver', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test1.my',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i driver ID
Devices
deploy_device - deploy device items from template
Deploys the device from the specified template.
http
POST /uc-api/deploy_device HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "device1", "c": "PORT=2,ID=5", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/deploy_device -H 'Content-Type: application/json' --data-raw '{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
wget
wget -S -O- http://localhost:8812/uc-api/deploy_device --header='Content-Type: application/json' --post-data='{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
httpie
echo '{
"c": "PORT=2,ID=5",
"k": "mykey",
"save": true,
"t": "device1"
}' | http POST http://localhost:8812/uc-api/deploy_device Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/deploy_device', headers={
'Content-Type': 'application/json',
}, json={
'c': 'PORT=2,ID=5',
'k': 'mykey',
'save': True,
't': 'device1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
list_device_tpl - list device templates
List available device templates from runtime/tpl
http
POST /uc-api/list_device_tpl HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/uc-api/list_device_tpl -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/uc-api/list_device_tpl --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/uc-api/list_device_tpl Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/list_device_tpl', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"name": "asic",
"type": "JSON"
},
{
"name": "device1",
"type": "YAML"
},
{
"name": "weatherapp",
"type": "JSON"
}
]
Parameters:
- k API key with masterkey permissions
undeploy_device - delete device items
Works in an opposite way to deploy_device - deploy device items from template function, destroying all items specified in the template.
http
POST /uc-api/undeploy_device HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "device1", "c": "PORT=2,ID=5" }
curl
curl -i -X POST http://localhost:8812/uc-api/undeploy_device -H 'Content-Type: application/json' --data-raw '{"c": "PORT=2,ID=5", "k": "mykey", "t": "device1"}'
wget
wget -S -O- http://localhost:8812/uc-api/undeploy_device --header='Content-Type: application/json' --post-data='{"c": "PORT=2,ID=5", "k": "mykey", "t": "device1"}'
httpie
echo '{
"c": "PORT=2,ID=5",
"k": "mykey",
"t": "device1"
}' | http POST http://localhost:8812/uc-api/undeploy_device Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/undeploy_device', headers={
'Content-Type': 'application/json',
}, json={
'c': 'PORT=2,ID=5',
'k': 'mykey',
't': 'device1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
Returns:
The function ignores missing items, so no errors are returned unless device configuration file is invalid.
update_device - update device items
Works similarly to deploy_device - deploy device items from template function but doesn’t create new items, updating the item configuration of the existing ones.
http
POST /uc-api/update_device HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "device1", "c": "PORT=2,ID=5", "save": true }
curl
curl -i -X POST http://localhost:8812/uc-api/update_device -H 'Content-Type: application/json' --data-raw '{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
wget
wget -S -O- http://localhost:8812/uc-api/update_device --header='Content-Type: application/json' --post-data='{"c": "PORT=2,ID=5", "k": "mykey", "save": true, "t": "device1"}'
httpie
echo '{
"c": "PORT=2,ID=5",
"k": "mykey",
"save": true,
"t": "device1"
}' | http POST http://localhost:8812/uc-api/update_device Content-Type:application/json
python-requests
requests.post('http://localhost:8812/uc-api/update_device', headers={
'Content-Type': 'application/json',
}, json={
'c': 'PORT=2,ID=5',
'k': 'mykey',
'save': True,
't': 'device1',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
UC UDP API
UC UDP API enables to call API action and update functions by sending a simple UDP packet.
Basics
As there is no feedback in UDP, it is not recommended to use UDP API in cases where reliability is critical, but its usability for programmable microcontrollers sometimes takes advantage.
To update the status of the item send the following UDP packet to API port:
<ID> u <status> [value]
(ID - item id, value - optional parameter).
To send action for the unit send the following UDP packet to API port:
<ID> <status> [value] [priority]
(value and priority** optional parameters).
If you needs to skip the parameter, set it to ‘None’. For example:
sensor1 u None 29.55
will keep sensor1 status and set value 29.55;
or
unit1 1 None 50
will run the action for unit1 for changing its status to 1, without changing the value, with priority 50.
Batch commands
You can specify multiple commands in one packet separating them with NL (n) symbol. Example:
sensor1 u 1 29.55
sensor2 u 1 26
sensor3 u 1 38
Encryption and authentication
You may specify in controller configuration to accept only encrypted packets from the specified hosts or networks. By default it’s recommended to accept unencrypted packets without authentication only in trusted networks. The packet is encrypted and signed with API key and can not be decrypted and used without having it, so API key acts both for encryption and authentication.
Encrypted packet format is:
|KEY_ID|ENCRYPTED_DATA
Where KEY_ID is API key ID and ENCRYPTED_DATA - UDP API packet (which may contain either single or multiple commands at once). The data is encrypted using Fernet - a symmetric encryption method which uses 128-bit AES in CBC mode and PKCS7 padding, with HMAC using SHA256 for authentication.
Fernet requires 32-bit base64-encoded key, so before data encryption, API key should be converted with the following: base64encode(sha256sum(api_key)).
Python example:
import hashlib
import base64
from cryptography.fernet import Fernet
api_key = 'mysecretapikey'
data = 'sensor1 u 1 29.55'
encryption_key = base64.b64encode(hashlib.sha256(api_key.encode()).digest())
ce = Fernet(encryption_key)
result = ce.encrypt(data.encode())
Fernet implementation is simple and pre-made libraries are available for all major programming languages.
Custom packets
You can send a custom packet to let it be parsed by loaded PHI.
Custom packet format is (\x = hex):
\x01 HANDLER_ID \x01 DATA
DATA is always transmitted to handler in binary format. Encryption, authentication and batch commands in custom packets are not supported.
LM API
Logic Manager API is used to manage lvars, rules and other logic elements
This document describes API methods for direct and JSON RPC calls. For RESTful API look LM RESTful API.
API basics
Standard API (direct method calling)
LM API functions are called through URL request
http://<ip_address:8817>/lm-api/function
If SSL is allowed in the controller configuration file, you can also use https calls.
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Standard API responses
Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.
API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.
Standard responses in status/body:
- 200 OK { “result”: “OK” } API call completed successfully.
Standard error responses in status:
- 400 Bad Request Invalid request params
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found method or resource/object doesn’t exist
- 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
In case API function has been failed, response body will contain JSON data with _error field, which contains error message.
{
"_error": "unable to add object, already present",
"result": "ERROR"
}
JSON RPC
Additionally, API supports JSON RPC 2.0 protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” }). There’s no error result, as JSON RPC sends errors in “error” field.
If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.
Note
JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.
JSON RPC API URL:
http://<ip_address:8817>/jrpc
JSON RPC error responses
JSON RPC calls return error codes equal to the codes of EVA API Client:
- 1 the item or resource is not found
- 2 access is denied with the set API key
- 6 Attempt to call undefined API method/function
- 10 API function failed (all errors not listed here fall within this category)
- 11 API function is called with invalid params
- 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
- 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
- 14 the method is not implemented in/for requested resource
Response field “message” may contain additional information about error.
Contents
- LM API
- API basics
- General functions
- LVar functions
- LVar management
- Decision matrix rules
- Logic control macros
- create_macro - create new macro
- destroy_macro - delete macro
- get_macro - get macro information
- groups_macro - get macro groups list
- list_macro_props - get macro configuration properties
- list_macros - get macro list
- result - macro execution result
- run - execute macro
- set_macro_prop - set macro configuration property
- Logic cycles
- create_cycle - create new cycle
- destroy_cycle - delete cycle
- get_cycle - get cycle information
- groups_cycle - get cycle groups list
- list_cycle_props - get cycle configuration properties
- list_cycles - get cycle list
- reset_cycle_stats - reset cycle statistic
- set_cycle_prop - set cycle property
- start_cycle - start cycle
- stop_cycle - stop cycle
- Macro extensions
- get_ext - get loaded extension information
- list_ext - get list of available macro extensions
- list_ext_mods - get list of available extension modules
- load_ext - load extension module
- modhelp_ext - get extension usage help
- modinfo_ext - get extension module info
- set_ext_prop - set extension configuration property
- unload_ext - unload macro extension
- Remote controllers
- append_controller - connect remote UC via HTTP
- disable_controller - disable connected controller
- enable_controller - enable connected controller
- get_controller - get connected controller information
- list_controller_props - get controller connection parameters
- list_controllers - get controllers list
- list_remote - get a list of items from connected UCs
- reload_controller - reload controller
- remove_controller - disconnect controller
- set_controller_prop - set controller connection parameters
- test_controller - test connection to remote controller
- Scheduled jobs
General functions
test - test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
POST /lm-api/test HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/test -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/test --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/test Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/test', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"db_update": 1,
"debug": true,
"file_management": true,
"layout": "enterprise",
"polldelay": 0.01,
"product_build": 2019031405,
"product_code": "lm",
"product_name": "EVA Logic Manager",
"result": "OK",
"setup_mode": false,
"system": "ws1-v1",
"time": 1553193499.7920787,
"uptime": 658,
"version": "3.2.0"
}
Parameters:
- k any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
login - log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /lm-api/login HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8817/lm-api/login -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8817/lm-api/login --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8817/lm-api/login Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/login', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- k valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
logout - log out and purge authentication token
Purges authentication token
http
POST /lm-api/logout HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7" }
curl
curl -i -X POST http://localhost:8812/lm-api/logout -H 'Content-Type: application/json' --data-raw '{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
wget
wget -S -O- http://localhost:8812/lm-api/logout --header='Content-Type: application/json' --post-data='{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
httpie
echo '{
"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
}' | http POST http://localhost:8812/lm-api/logout Content-Type:application/json
python-requests
requests.post('http://localhost:8812/lm-api/logout', headers={
'Content-Type': 'application/json',
}, json={
'k': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid token
LVar functions
clear - clear lvar state
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.
http
POST /lm-api/clear HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/clear -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/clear --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/clear Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/clear', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
decrement - decrement lvar value
Decrement value of a logic variable. Initial value should be number
http
POST /lm-api/decrement HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/decrement -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/decrement --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/decrement Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/decrement', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
groups - get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
POST /lm-api/groups HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/groups -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/groups --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/groups Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/groups', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"nogroup",
"tests",
"timers"
]
Parameters:
- k valid API key
- p item type (must be set to lvar [LV])
increment - increment lvar value
Increment value of a logic variable. Initial value should be number
http
POST /lm-api/increment HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/increment -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/increment --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/increment Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/increment', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
reset - reset lvar state
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.
http
POST /lm-api/reset HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/reset -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/reset --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/reset Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/reset', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
set - set lvar state
Set status and value of a logic variable.
http
POST /lm-api/set HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1", "s": 1, "v": 29.445 }
curl
curl -i -X POST http://localhost:8817/lm-api/set -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey", "s": 1, "v": 29.445}'
wget
wget -S -O- http://localhost:8817/lm-api/set --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey", "s": 1, "v": 29.445}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey",
"s": 1,
"v": 29.445
}' | http POST http://localhost:8817/lm-api/set Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
's': 1,
'v': 29.445,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
Optionally:
- s lvar status
- v lvar value
state - get lvar state
State of lvar or all lvars can be obtained using state command.
http
POST /lm-api/state HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/state -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/state --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/state Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/state', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"expires": 0,
"full_id": "nogroup/flag1",
"group": "nogroup",
"id": "flag1",
"oid": "lvar:nogroup/flag1",
"set_time": 1528751049.3848495,
"status": 1,
"type": "lvar",
"value": "1"
},
{
"expires": 5.0,
"full_id": "nogroup/timer1",
"group": "nogroup",
"id": "timer1",
"oid": "lvar:nogroup/timer1",
"set_time": 1552049990.9313273,
"status": -1,
"type": "lvar",
"value": "null"
},
{
"expires": 15.0,
"full_id": "tests/lvar1",
"group": "tests",
"id": "lvar1",
"oid": "lvar:tests/lvar1",
"set_time": 1553193500.1979027,
"status": 1,
"type": "lvar",
"value": "null"
},
{
"expires": 30.0,
"full_id": "tests/lvar2",
"group": "tests",
"id": "lvar2",
"oid": "lvar:tests/lvar2",
"set_time": 1553193499.8252523,
"status": 1,
"type": "lvar",
"value": "null"
},
{
"expires": 100.0,
"full_id": "timers/timer1",
"group": "timers",
"id": "timer1",
"oid": "lvar:timers/timer1",
"set_time": 1552062897.9593153,
"status": -1,
"type": "lvar",
"value": "null"
}
]
Parameters:
- k valid API key
Optionally:
- p item type (none or lvar [LV])
- 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.
http
POST /lm-api/state_history HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/state_history -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/state_history --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/state_history Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/state_history', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"status": [
1,
1,
1
],
"t": [
1553193500.1192024,
1553193500.199146,
1553193500.2409995
],
"value": [
1.0,
null,
null
]
}
Parameters:
- k valid API key
- a history notifier id (default: db_1)
- i item oids or full ids, list or comma separated
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
- g output format (“list”, “dict” or “chart”, default is “list”)
- c options for chart (dict or comma separated)
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
- type: chart type (line or bar, default is line)
- tf: chart time format
- out: output format (svg, png, default is svg),
- style: chart style (without “Style” suffix, e.g. Dark)
- other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
toggle - toggle lvar state
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.
http
POST /lm-api/toggle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/toggle -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/toggle --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/toggle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/toggle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
LVar management
list - list lvars
http
POST /lm-api/list HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "flag 1",
"expires": 0,
"full_id": "nogroup/flag1",
"group": "nogroup",
"id": "flag1",
"oid": "lvar:nogroup/flag1",
"set_time": 1528751049.3848495,
"type": "lvar"
},
{
"description": "",
"expires": 5.0,
"full_id": "nogroup/timer1",
"group": "nogroup",
"id": "timer1",
"oid": "lvar:nogroup/timer1",
"set_time": 1552049990.9313273,
"type": "lvar"
},
{
"description": "",
"expires": 0,
"full_id": "tests/lvar1",
"group": "tests",
"id": "lvar1",
"oid": "lvar:tests/lvar1",
"set_time": 1553193500.117168,
"type": "lvar"
},
{
"description": "",
"expires": 30.0,
"full_id": "tests/lvar2",
"group": "tests",
"id": "lvar2",
"oid": "lvar:tests/lvar2",
"set_time": 1553193499.8252523,
"type": "lvar"
},
{
"description": "",
"expires": 100.0,
"full_id": "timers/timer1",
"group": "timers",
"id": "timer1",
"oid": "lvar:timers/timer1",
"set_time": 1552062897.9593153,
"type": "lvar"
}
]
Parameters:
- k API key with master permissions
Optionally:
- g filter by item group
Returns:
the list of all lvars available
create_lvar - create lvar
Create new lvar
http
POST /lm-api/create_lvar HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/create_lvar -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8817/lm-api/create_lvar --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8817/lm-api/create_lvar Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/create_lvar', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"expires": 0,
"full_id": "tests/lvar1",
"group": "tests",
"id": "lvar1",
"oid": "lvar:tests/lvar1",
"set_time": 1553193499.8059733,
"status": 1,
"type": "lvar",
"value": "null"
}
Parameters:
- k API key with master permissions
- i lvar id
Optionally:
- g lvar group
- save save lvar configuration immediately
destroy_lvar - delete lvar
http
POST /lm-api/destroy_lvar HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/destroy_lvar -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/destroy_lvar --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/destroy_lvar Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/destroy_lvar', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i lvar id
get_config - get lvar configuration
http
POST /lm-api/get_config HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_config -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_config --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_config Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_config', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"expires": 0,
"full_id": "tests/lvar1",
"group": "tests",
"id": "lvar1",
"oid": "lvar:tests/lvar1",
"set_time": 1553193500.117168,
"type": "lvar"
}
Parameters:
- k API key with master permissions
- i lvaar id
Returns:
complete lvar configuration.
list_props - list lvar properties
Get all editable parameters of the lvar confiugration.
http
POST /lm-api/list_props HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_props -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_props --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_props Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"expires": 0,
"mqtt_update": null,
"set_time": 1553193500.117168,
"update_delay": 0,
"update_exec": null,
"update_interval": 0,
"update_timeout": null
}
Parameters:
- k API key with master permissions
- i item id
save_config - save lvar configuration
Saves lvar. configuration on disk (even if it hasn’t been changed)
http
POST /lm-api/save_config HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1" }
curl
curl -i -X POST http://localhost:8817/lm-api/save_config -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/save_config --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/save_config Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/save_config', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i lvar id
set_prop - set lvar property
Set configuration parameters of the lvar.
http
POST /lm-api/set_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "lvar:tests/lvar1", "p": "expires", "v": 15 }
curl
curl -i -X POST http://localhost:8817/lm-api/set_prop -H 'Content-Type: application/json' --data-raw '{"i": "lvar:tests/lvar1", "k": "mykey", "p": "expires", "v": 15}'
wget
wget -S -O- http://localhost:8817/lm-api/set_prop --header='Content-Type: application/json' --post-data='{"i": "lvar:tests/lvar1", "k": "mykey", "p": "expires", "v": 15}'
httpie
echo '{
"i": "lvar:tests/lvar1",
"k": "mykey",
"p": "expires",
"v": 15
}' | http POST http://localhost:8817/lm-api/set_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'lvar:tests/lvar1',
'k': 'mykey',
'p': 'expires',
'v': 15,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
Decision matrix rules
create_rule - create new rule
Creates new decision rule. Rule id (UUID) is generated automatically unless specified.
http
POST /lm-api/create_rule HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/create_rule -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/create_rule --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/create_rule Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/create_rule', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "9b317323-00e5-4e11-8573-33cdcada1d12",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/9b317323-00e5-4e11-8573-33cdcada1d12",
"priority": 100,
"type": "dmatrix_rule"
}
Parameters:
- k API key with master permissions
Optionally:
- u rule UUID to set
- v rule properties (dict)
- save save rule configuration immediately
destroy_rule - delete rule
Deletes decision rule.
http
POST /lm-api/destroy_rule HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "4c6e8c99-56fe-490c-8442-4936ba777498" }
curl
curl -i -X POST http://localhost:8817/lm-api/destroy_rule -H 'Content-Type: application/json' --data-raw '{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/destroy_rule --header='Content-Type: application/json' --post-data='{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey"}'
httpie
echo '{
"i": "4c6e8c99-56fe-490c-8442-4936ba777498",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/destroy_rule Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/destroy_rule', headers={
'Content-Type': 'application/json',
}, json={
'i': '4c6e8c99-56fe-490c-8442-4936ba777498',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i rule id
get_rule - get rule information
http
POST /lm-api/get_rule HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "4c6e8c99-56fe-490c-8442-4936ba777498" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_rule -H 'Content-Type: application/json' --data-raw '{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_rule --header='Content-Type: application/json' --post-data='{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey"}'
httpie
echo '{
"i": "4c6e8c99-56fe-490c-8442-4936ba777498",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_rule Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_rule', headers={
'Content-Type': 'application/json',
}, json={
'i': '4c6e8c99-56fe-490c-8442-4936ba777498',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "4c6e8c99-56fe-490c-8442-4936ba777498",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/4c6e8c99-56fe-490c-8442-4936ba777498",
"priority": 100,
"type": "dmatrix_rule"
}
Parameters:
- k valid API key
- i rule id
list_rule_props - list rule properties
Get all editable parameters of the decision rule.
http
POST /lm-api/list_rule_props HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "4c6e8c99-56fe-490c-8442-4936ba777498" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_rule_props -H 'Content-Type: application/json' --data-raw '{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_rule_props --header='Content-Type: application/json' --post-data='{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey"}'
httpie
echo '{
"i": "4c6e8c99-56fe-490c-8442-4936ba777498",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_rule_props Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_rule_props', headers={
'Content-Type': 'application/json',
}, json={
'i': '4c6e8c99-56fe-490c-8442-4936ba777498',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"break_after_exec": false,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"priority": 100
}
Parameters:
- k valid API key
- i rule id
list_rules - get rules list
Get the list of all available decision rules.
http
POST /lm-api/list_rules HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_rules -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_rules --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_rules Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_rules', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "4c6e8c99-56fe-490c-8442-4936ba777498",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/4c6e8c99-56fe-490c-8442-4936ba777498",
"priority": 100,
"type": "dmatrix_rule"
},
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "9b317323-00e5-4e11-8573-33cdcada1d12",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/9b317323-00e5-4e11-8573-33cdcada1d12",
"priority": 100,
"type": "dmatrix_rule"
},
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "cc7de0ba-04a1-4161-ad73-588861b6e1ef",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/cc7de0ba-04a1-4161-ad73-588861b6e1ef",
"priority": 100,
"type": "dmatrix_rule"
}
]
Parameters:
- k valid API key
set_rule_prop - set rule parameters
Set configuration parameters of the decision rule.
Note
Master key is required for batch set.
http
POST /lm-api/set_rule_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "4c6e8c99-56fe-490c-8442-4936ba777498", "p": "for_initial", "v": "any", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/set_rule_prop -H 'Content-Type: application/json' --data-raw '{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey", "p": "for_initial", "save": true, "v": "any"}'
wget
wget -S -O- http://localhost:8817/lm-api/set_rule_prop --header='Content-Type: application/json' --post-data='{"i": "4c6e8c99-56fe-490c-8442-4936ba777498", "k": "mykey", "p": "for_initial", "save": true, "v": "any"}'
httpie
echo '{
"i": "4c6e8c99-56fe-490c-8442-4936ba777498",
"k": "mykey",
"p": "for_initial",
"save": true,
"v": "any"
}' | http POST http://localhost:8817/lm-api/set_rule_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_rule_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': '4c6e8c99-56fe-490c-8442-4936ba777498',
'k': 'mykey',
'p': 'for_initial',
'save': True,
'v': 'any',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i rule id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
Logic control macros
create_macro - create new macro
Creates new macro. Macro code should be put in xc/lm manually.
http
POST /lm-api/create_macro HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro" }
curl
curl -i -X POST http://localhost:8817/lm-api/create_macro -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/create_macro --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/create_macro Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/create_macro', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/test_macro",
"group": "tests",
"id": "test_macro",
"oid": "lmacro:tests/test_macro",
"type": "lmacro"
}
Parameters:
- k API key with master permissions
- i macro id
Optionally:
- g macro group
destroy_macro - delete macro
Deletes macro.
http
POST /lm-api/destroy_macro HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro" }
curl
curl -i -X POST http://localhost:8817/lm-api/destroy_macro -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/destroy_macro --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/destroy_macro Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/destroy_macro', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i macro id
get_macro - get macro information
http
POST /lm-api/get_macro HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_macro -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_macro --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_macro Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_macro', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"description": "",
"full_id": "tests/test_macro",
"group": "tests",
"id": "test_macro",
"oid": "lmacro:tests/test_macro",
"type": "lmacro"
}
Parameters:
- k valid API key
- i macro id
groups_macro - get macro groups list
Get the list of macros. Useful e.g. for custom interfaces.
http
POST /lm-api/groups_macro HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/groups_macro -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/groups_macro --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/groups_macro Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/groups_macro', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"tests"
]
Parameters:
- k valid API key
list_macro_props - get macro configuration properties
http
POST /lm-api/list_macro_props HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_macro_props -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_macro_props --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_macro_props Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_macro_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"action_exec": null,
"description": "",
"pass_errors": false,
"send_critical": false
}
Parameters:
- k API key with master permissions
- i macro id
list_macros - get macro list
Get the list of all available macros.
http
POST /lm-api/list_macros HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_macros -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_macros --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_macros Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_macros', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"action_enabled": true,
"description": "",
"full_id": "tests/test1",
"group": "tests",
"id": "test1",
"oid": "lmacro:tests/test1",
"type": "lmacro"
},
{
"action_enabled": true,
"description": "",
"full_id": "tests/test2",
"group": "tests",
"id": "test2",
"oid": "lmacro:tests/test2",
"type": "lmacro"
},
{
"action_enabled": true,
"description": "",
"full_id": "tests/test_macro",
"group": "tests",
"id": "test_macro",
"oid": "lmacro:tests/test_macro",
"type": "lmacro"
},
{
"action_enabled": true,
"description": "",
"full_id": "tests/test_macro2",
"group": "tests",
"id": "test_macro2",
"oid": "lmacro:tests/test_macro2",
"type": "lmacro"
}
]
Parameters:
- k valid API key
Optionally:
- g filter by group
result - macro execution result
Get macro execution results either by action uuid or by macro id.
http
POST /lm-api/result HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro" }
curl
curl -i -X POST http://localhost:8817/lm-api/result -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/result --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/result Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/result', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"args": [],
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0097811,
"item_group": "tests",
"item_id": "test_macro",
"item_oid": "lmacro:tests/test_macro",
"item_type": "lmacro",
"kwargs": {},
"out": "test passed",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559868831.1551707,
"created": 1559868831.1453896,
"pending": 1559868831.1458647,
"queued": 1559868831.1469553,
"running": 1559868831.1479862
},
"uuid": "7707c382-eefa-48d2-9b5e-92d114af4e85"
}
]
Parameters:
- k valid API key
Optionally:
- u action uuid or
- i macro 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
run - execute macro
Execute a macro with the specified arguments.
http
POST /lm-api/run HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro" }
curl
curl -i -X POST http://localhost:8817/lm-api/run -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/run --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/run Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/run', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"args": [],
"err": "",
"exitcode": null,
"finished": false,
"finished_in": null,
"item_group": "tests",
"item_id": "test_macro",
"item_oid": "lmacro:tests/test_macro",
"item_type": "lmacro",
"kwargs": {},
"out": "",
"priority": 100,
"status": "running",
"time": {
"created": 1559868831.9307947,
"pending": 1559868831.9313061,
"queued": 1559868831.9320123,
"running": 1559868831.9324815
},
"uuid": "c1ac8b97-54c3-40e3-9db0-df859d9585c7"
}
Parameters:
- k valid API key
- i macro id
Optionally:
- a macro arguments, array or space separated
- kw macro keyword arguments, name=value, comma separated or dict
- 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”
set_macro_prop - set macro configuration property
Set configuration parameters of the macro.
http
POST /lm-api/set_macro_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_macro", "p": "pass_errors", "v": true, "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/set_macro_prop -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_macro", "k": "mykey", "p": "pass_errors", "save": true, "v": true}'
wget
wget -S -O- http://localhost:8817/lm-api/set_macro_prop --header='Content-Type: application/json' --post-data='{"i": "tests/test_macro", "k": "mykey", "p": "pass_errors", "save": true, "v": true}'
httpie
echo '{
"i": "tests/test_macro",
"k": "mykey",
"p": "pass_errors",
"save": true,
"v": true
}' | http POST http://localhost:8817/lm-api/set_macro_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_macro_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_macro',
'k': 'mykey',
'p': 'pass_errors',
'save': True,
'v': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
Logic cycles
create_cycle - create new cycle
Creates new cycle.
http
POST /lm-api/create_cycle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/create_cycle -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/create_cycle --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/create_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/create_cycle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/test_cycle",
"group": "tests",
"ict": 100,
"id": "test_cycle",
"interval": 1,
"macro": null,
"oid": "lcycle:tests/test_cycle",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "1.0000"
}
Parameters:
- k API key with master permissions
- i cycle id
Optionally:
- g cycle group
destroy_cycle - delete cycle
Deletes cycle. If cycle is running, it is stopped before deletion.
http
POST /lm-api/destroy_cycle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/destroy_cycle -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/destroy_cycle --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/destroy_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/destroy_cycle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i cycle id
get_cycle - get cycle information
http
POST /lm-api/get_cycle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_cycle -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_cycle --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_cycle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"avg": 1,
"description": "",
"full_id": "tests/test_cycle",
"group": "tests",
"ict": 20,
"id": "test_cycle",
"interval": 1,
"iterations": 0,
"macro": "tests/test_macro",
"oid": "lcycle:tests/test_cycle",
"on_error": null,
"status": 1,
"type": "lcycle",
"value": "1.0000"
}
Parameters:
- k valid API key
- i cycle id
Returns:
field “value” contains real average cycle interval
groups_cycle - get cycle groups list
Get the list of cycles. Useful e.g. for custom interfaces.
http
POST /lm-api/groups_cycle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/groups_cycle -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/groups_cycle --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/groups_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/groups_cycle', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"tests"
]
Parameters:
- k valid API key
list_cycle_props - get cycle configuration properties
http
POST /lm-api/list_cycle_props HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_cycle_props -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_cycle_props --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_cycle_props Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_cycle_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"autostart": false,
"description": "",
"ict": 20,
"interval": 1,
"macro": "tests/test_macro",
"on_error": null
}
Parameters:
- k API key with master permissions
- i cycle id
list_cycles - get cycle list
Get the list of all available cycles.
http
POST /lm-api/list_cycles HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_cycles -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_cycles --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_cycles Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_cycles', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"avg": 0.0105,
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"ict": 20,
"id": "cycle1",
"interval": 0.01,
"iterations": 275,
"macro": "tests/test",
"oid": "lcycle:tests/cycle1",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "275,0.0105,"
},
{
"avg": 0.5,
"description": "test 2Hz cycle",
"full_id": "tests/test1",
"group": "tests",
"ict": 100,
"id": "test1",
"interval": 0.5,
"iterations": 0,
"macro": "tests/test1",
"oid": "lcycle:tests/test1",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "0,0.5000,"
}
]
Parameters:
- k valid API key
Optionally:
- g filter by group
reset_cycle_stats - reset cycle statistic
http
POST /lm-api/reset_cycle_stats HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/reset_cycle_stats -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/reset_cycle_stats --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/reset_cycle_stats Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/reset_cycle_stats', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i cycle id
set_cycle_prop - set cycle property
Set configuration parameters of the cycle.
http
POST /lm-api/set_cycle_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle", "p": "macro", "v": "tests/test_macro", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/set_cycle_prop -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey", "p": "macro", "save": true, "v": "tests/test_macro"}'
wget
wget -S -O- http://localhost:8817/lm-api/set_cycle_prop --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey", "p": "macro", "save": true, "v": "tests/test_macro"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey",
"p": "macro",
"save": true,
"v": "tests/test_macro"
}' | http POST http://localhost:8817/lm-api/set_cycle_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_cycle_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
'p': 'macro',
'save': True,
'v': 'tests/test_macro',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i item id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
start_cycle - start cycle
http
POST /lm-api/start_cycle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/start_cycle -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/start_cycle --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/start_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/start_cycle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i cycle id
stop_cycle - stop cycle
http
POST /lm-api/stop_cycle HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "tests/test_cycle" }
curl
curl -i -X POST http://localhost:8817/lm-api/stop_cycle -H 'Content-Type: application/json' --data-raw '{"i": "tests/test_cycle", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/stop_cycle --header='Content-Type: application/json' --post-data='{"i": "tests/test_cycle", "k": "mykey"}'
httpie
echo '{
"i": "tests/test_cycle",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/stop_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/stop_cycle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test_cycle',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i cycle id
Optionally:
- wait wait until cycle is stopped
Macro extensions
get_ext - get loaded extension information
http
POST /lm-api/get_ext HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "test_a" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_ext -H 'Content-Type: application/json' --data-raw '{"i": "test_a", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_ext --header='Content-Type: application/json' --post-data='{"i": "test_a", "k": "mykey"}'
httpie
echo '{
"i": "test_a",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_ext Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_ext', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test_a',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"sdir": "/opt/data/snd"
},
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"id": "test_a",
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- i extension ID
list_ext - get list of available macro extensions
http
POST /lm-api/list_ext HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_ext -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_ext --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_ext Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_ext', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"id": "a1",
"mod": "audio"
},
{
"id": "test_a",
"mod": "audio"
},
{
"id": "test_a2",
"mod": "audio"
}
]
Parameters:
- k API key with master permissions
Optionally:
- full get full information
list_ext_mods - get list of available extension modules
http
POST /lm-api/list_ext_mods HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_ext_mods -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_ext_mods --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_ext_mods Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_ext_mods', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"id": null,
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
},
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Push client for Roboger",
"help": "\nPush client for Roboger event pager (https://www.roboger.com,\nhttps://github.com/alttch/roboger). Refer to pyrpush module documentation for\nmore info: https://pypi.org/project/pyrpush/\n",
"id": null,
"license": "Apache License 2.0",
"mod": "rpush",
"mods_required": [
"pyrpush"
],
"version": "1.0.0"
},
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Run macro on remote LM PLC",
"help": "\nAllows to run macros on remote LM PLC\n",
"id": null,
"license": "Apache License 2.0",
"mod": "run_remote",
"mods_required": [],
"version": "1.0.0"
},
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Text-to-speech via ttsbroker",
"help": "\nText-to-speech engine via ttsbroker Python module. Refer to module\ndocumentation for more info: https://pypi.org/project/ttsbroker/\n",
"id": null,
"license": "Apache License 2.0",
"mod": "tts",
"mods_required": [
"ttsbroker"
],
"version": "1.0.0"
}
]
Parameters:
- k API key with master permissions
load_ext - load extension module
Loads:doc:macro extension</lm/ext>.
http
POST /lm-api/load_ext HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "test_a", "m": "audio", "c": "sdir=/opt/data/snd", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/load_ext -H 'Content-Type: application/json' --data-raw '{"c": "sdir=/opt/data/snd", "i": "test_a", "k": "mykey", "m": "audio", "save": true}'
wget
wget -S -O- http://localhost:8817/lm-api/load_ext --header='Content-Type: application/json' --post-data='{"c": "sdir=/opt/data/snd", "i": "test_a", "k": "mykey", "m": "audio", "save": true}'
httpie
echo '{
"c": "sdir=/opt/data/snd",
"i": "test_a",
"k": "mykey",
"m": "audio",
"save": true
}' | http POST http://localhost:8817/lm-api/load_ext Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/load_ext', headers={
'Content-Type': 'application/json',
}, json={
'c': 'sdir=/opt/data/snd',
'i': 'test_a',
'k': 'mykey',
'm': 'audio',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"sdir": "/opt/data/snd"
},
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"id": "test_a",
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- i extension ID
- m extension module
Optionally:
- c extension configuration
- save save extension configuration after successful call
modhelp_ext - get extension usage help
http
POST /lm-api/modhelp_ext HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "m": "audio", "c": "functions" }
curl
curl -i -X POST http://localhost:8817/lm-api/modhelp_ext -H 'Content-Type: application/json' --data-raw '{"c": "functions", "k": "mykey", "m": "audio"}'
wget
wget -S -O- http://localhost:8817/lm-api/modhelp_ext --header='Content-Type: application/json' --post-data='{"c": "functions", "k": "mykey", "m": "audio"}'
httpie
echo '{
"c": "functions",
"k": "mykey",
"m": "audio"
}' | http POST http://localhost:8817/lm-api/modhelp_ext Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/modhelp_ext', headers={
'Content-Type': 'application/json',
}, json={
'c': 'functions',
'k': 'mykey',
'm': 'audio',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"play(soundfile, gain=0, wait=True)": "Play sound file"
}
Parameters:
- k API key with master permissions
- m extension name (without .py extension)
- c help context (cfg or functions)
modinfo_ext - get extension module info
http
POST /lm-api/modinfo_ext HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "m": "audio" }
curl
curl -i -X POST http://localhost:8817/lm-api/modinfo_ext -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "audio"}'
wget
wget -S -O- http://localhost:8817/lm-api/modinfo_ext --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "audio"}'
httpie
echo '{
"k": "mykey",
"m": "audio"
}' | http POST http://localhost:8817/lm-api/modinfo_ext Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/modinfo_ext', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'm': 'audio',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
}
Parameters:
- k API key with master permissions
- m extension module name (without .py extension)
set_ext_prop - set extension configuration property
appends property to extension configuration and reloads module
http
POST /lm-api/set_ext_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "test_a", "p": "d", "v": 2, "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/set_ext_prop -H 'Content-Type: application/json' --data-raw '{"i": "test_a", "k": "mykey", "p": "d", "save": true, "v": 2}'
wget
wget -S -O- http://localhost:8817/lm-api/set_ext_prop --header='Content-Type: application/json' --post-data='{"i": "test_a", "k": "mykey", "p": "d", "save": true, "v": 2}'
httpie
echo '{
"i": "test_a",
"k": "mykey",
"p": "d",
"save": true,
"v": 2
}' | http POST http://localhost:8817/lm-api/set_ext_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_ext_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test_a',
'k': 'mykey',
'p': 'd',
'save': True,
'v': 2,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i extension id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
unload_ext - unload macro extension
http
POST /lm-api/unload_ext HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "test_a" }
curl
curl -i -X POST http://localhost:8817/lm-api/unload_ext -H 'Content-Type: application/json' --data-raw '{"i": "test_a", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/unload_ext --header='Content-Type: application/json' --post-data='{"i": "test_a", "k": "mykey"}'
httpie
echo '{
"i": "test_a",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/unload_ext Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/unload_ext', headers={
'Content-Type': 'application/json',
}, json={
'i': 'test_a',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i extension ID
Remote controllers
append_controller - connect remote UC via HTTP
Connects remote UC controller to the local.
http
POST /lm-api/append_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "u": "localhost", "a": "secretkey", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/append_controller -H 'Content-Type: application/json' --data-raw '{"a": "secretkey", "k": "mykey", "save": true, "u": "localhost"}'
wget
wget -S -O- http://localhost:8817/lm-api/append_controller --header='Content-Type: application/json' --post-data='{"a": "secretkey", "k": "mykey", "save": true, "u": "localhost"}'
httpie
echo '{
"a": "secretkey",
"k": "mykey",
"save": true,
"u": "localhost"
}' | http POST http://localhost:8817/lm-api/append_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/append_controller', headers={
'Content-Type': 'application/json',
}, json={
'a': 'secretkey',
'k': 'mykey',
'save': True,
'u': 'localhost',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- k API key with master permissions
- u UC API uri (proto://host:port, port not required if default)
- a remote controller API key ($key to use local key)
Optionally:
- m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)
- s verify remote SSL certificate or pass invalid
- t timeout (seconds) for the remote controller API calls
- save save connected controller configuration on the disk immediately after creation
disable_controller - disable connected controller
http
POST /lm-api/disable_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/disable_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8817/lm-api/disable_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8817/lm-api/disable_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/disable_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
Optionally:
- save save configuration after successful call
enable_controller - enable connected controller
http
POST /lm-api/enable_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/enable_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8817/lm-api/enable_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8817/lm-api/enable_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/enable_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
Optionally:
- save save configuration after successful call
get_controller - get connected controller information
http
POST /lm-api/get_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- k API key with master permissions
- i controller id
list_controller_props - get controller connection parameters
http
POST /lm-api/list_controller_props HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_controller_props -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_controller_props --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_controller_props Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_controller_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"key": "secretkey",
"mqtt_update": null,
"reload_interval": 300,
"retries": 2,
"ssl_verify": true,
"static": true,
"timeout": 5.0,
"uri": "http://localhost:8812"
}
Parameters:
- k API key with master permissions
- i controller id
list_controllers - get controllers list
Get the list of all connected UC controllers.
http
POST /lm-api/list_controllers HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_controllers -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_controllers --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_controllers Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_controllers', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[]
Parameters:
- k API key with master permissions
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.
http
POST /lm-api/list_remote HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_remote -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_remote --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_remote Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_remote', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "env/temp_test",
"group": "env",
"id": "temp_test",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"oid": "sensor:env/temp_test",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"action_enabled": true,
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "nogroup/test2",
"group": "nogroup",
"id": "test2",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"nstatus": -1,
"nvalue": "null",
"oid": "unit:nogroup/test2",
"status": -1,
"status_labels": [
{
"label": "OFF",
"status": 0
},
{
"label": "ON",
"status": 1
}
],
"type": "unit",
"value": "null"
}
]
Parameters:
- k API key with master permissions
Optionally:
- i controller id
- g filter by item group
- p filter by item type
reload_controller - reload controller
Reloads items from connected UC
http
POST /lm-api/reload_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8817/lm-api/reload_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/reload_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/reload_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/reload_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
remove_controller - disconnect controller
http
POST /lm-api/remove_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8817/lm-api/remove_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/remove_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/remove_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/remove_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
set_controller_prop - set controller connection parameters
http
POST /lm-api/set_controller_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1", "p": "reload_interval", "v": 60, "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/set_controller_prop -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey", "p": "reload_interval", "save": true, "v": 60}'
wget
wget -S -O- http://localhost:8817/lm-api/set_controller_prop --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey", "p": "reload_interval", "save": true, "v": 60}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey",
"p": "reload_interval",
"save": true,
"v": 60
}' | http POST http://localhost:8817/lm-api/set_controller_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_controller_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
'p': 'reload_interval',
'save': True,
'v': 60,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller 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_controller - test connection to remote controller
http
POST /lm-api/test_controller HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8817/lm-api/test_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/test_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/test_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/test_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
Scheduled jobs
create_job - create new job
Creates new scheduled job. Job id (UUID) is generated automatically unless specified.
http
POST /lm-api/create_job HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/create_job -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/create_job --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/create_job Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/create_job', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": false,
"every": "",
"id": "93061b49-3e20-458f-95da-4976eb608358",
"last": null,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "job:jobs/93061b49-3e20-458f-95da-4976eb608358",
"type": "job"
}
Parameters:
- k API key with master permissions
Optionally:
- u job UUID to set
- v job properties (dict)
- save save unit configuration immediately
destroy_job - delete job
Deletes scheduled job.
http
POST /lm-api/destroy_job HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "9c6e8c99-56fe-490c-8442-4936ba777499" }
curl
curl -i -X POST http://localhost:8817/lm-api/destroy_job -H 'Content-Type: application/json' --data-raw '{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/destroy_job --header='Content-Type: application/json' --post-data='{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey"}'
httpie
echo '{
"i": "9c6e8c99-56fe-490c-8442-4936ba777499",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/destroy_job Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/destroy_job', headers={
'Content-Type': 'application/json',
}, json={
'i': '9c6e8c99-56fe-490c-8442-4936ba777499',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i job id
get_job - get job information
http
POST /lm-api/get_job HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "9c6e8c99-56fe-490c-8442-4936ba777499" }
curl
curl -i -X POST http://localhost:8817/lm-api/get_job -H 'Content-Type: application/json' --data-raw '{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/get_job --header='Content-Type: application/json' --post-data='{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey"}'
httpie
echo '{
"i": "9c6e8c99-56fe-490c-8442-4936ba777499",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/get_job Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/get_job', headers={
'Content-Type': 'application/json',
}, json={
'i': '9c6e8c99-56fe-490c-8442-4936ba777499',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"every": "",
"id": "9c6e8c99-56fe-490c-8442-4936ba777499",
"last": null,
"macro": "tests/test1",
"macro_args": [
"test"
],
"macro_kwargs": {},
"oid": "job:jobs/9c6e8c99-56fe-490c-8442-4936ba777499",
"type": "job"
}
Parameters:
- k API key with master permissions
- i job id
list_job_props - list job properties
Get all editable parameters of the scheduled job.
http
POST /lm-api/list_job_props HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "9c6e8c99-56fe-490c-8442-4936ba777499" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_job_props -H 'Content-Type: application/json' --data-raw '{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_job_props --header='Content-Type: application/json' --post-data='{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey"}'
httpie
echo '{
"i": "9c6e8c99-56fe-490c-8442-4936ba777499",
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_job_props Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_job_props', headers={
'Content-Type': 'application/json',
}, json={
'i': '9c6e8c99-56fe-490c-8442-4936ba777499',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"every": "",
"macro": "tests/test1",
"macro_args": [
"test"
],
"macro_kwargs": {}
}
Parameters:
- k API key with master permissions
- i job id
list_jobs - get jobs list
Get the list of all available scheduled jobs.
http
POST /lm-api/list_jobs HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8817/lm-api/list_jobs -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8817/lm-api/list_jobs --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8817/lm-api/list_jobs Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/list_jobs', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "",
"enabled": false,
"every": "",
"id": "9d8a338f-cdc4-46ac-8610-ba3b1597c73e",
"last": null,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "job:jobs/9d8a338f-cdc4-46ac-8610-ba3b1597c73e",
"type": "job"
},
{
"description": "",
"enabled": false,
"every": "",
"id": "7545a768-ce67-44ad-9544-2a54ad6c7e83",
"last": null,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "job:jobs/7545a768-ce67-44ad-9544-2a54ad6c7e83",
"type": "job"
}
]
Parameters:
- k API key with master permissions
set_job_prop - set job parameters
Set configuration parameters of the scheduled job.
http
POST /lm-api/set_job_prop HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "k": "mykey", "i": "9c6e8c99-56fe-490c-8442-4936ba777499", "p": "macro_args", "v": "test", "save": true }
curl
curl -i -X POST http://localhost:8817/lm-api/set_job_prop -H 'Content-Type: application/json' --data-raw '{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey", "p": "macro_args", "save": true, "v": "test"}'
wget
wget -S -O- http://localhost:8817/lm-api/set_job_prop --header='Content-Type: application/json' --post-data='{"i": "9c6e8c99-56fe-490c-8442-4936ba777499", "k": "mykey", "p": "macro_args", "save": true, "v": "test"}'
httpie
echo '{
"i": "9c6e8c99-56fe-490c-8442-4936ba777499",
"k": "mykey",
"p": "macro_args",
"save": true,
"v": "test"
}' | http POST http://localhost:8817/lm-api/set_job_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8817/lm-api/set_job_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': '9c6e8c99-56fe-490c-8442-4936ba777499',
'k': 'mykey',
'p': 'macro_args',
'save': True,
'v': 'test',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i job id
- p property name (or empty for batch set)
Optionally:
- v propery value (or dict for batch set)
- save save configuration after successful call
SFA API
SCADA Final Aggregator API is used to manage EVA ICS cloud and aggregated resources.
This document describes API methods for direct and JSON RPC calls. For RESTful API look SFA RESTful API.
API basics
Standard API (direct method calling)
SFA API functions are called through URL request
http://<ip_address:8828>/sfa-api/function
If SSL is allowed in the controller configuration file, you can also use https calls.
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Standard API responses
Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.
API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.
Standard responses in status/body:
- 200 OK { “result”: “OK” } API call completed successfully.
Standard error responses in status:
- 400 Bad Request Invalid request params
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found method or resource/object doesn’t exist
- 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
In case API function has been failed, response body will contain JSON data with _error field, which contains error message.
{
"_error": "unable to add object, already present",
"result": "ERROR"
}
JSON RPC
Additionally, API supports JSON RPC 2.0 protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” }). There’s no error result, as JSON RPC sends errors in “error” field.
If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.
Note
JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.
JSON RPC API URL:
http://<ip_address:8828>/jrpc
JSON RPC error responses
JSON RPC calls return error codes equal to the codes of EVA API Client:
- 1 the item or resource is not found
- 2 access is denied with the set API key
- 6 Attempt to call undefined API method/function
- 10 API function failed (all errors not listed here fall within this category)
- 11 API function is called with invalid params
- 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
- 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
- 14 the method is not implemented in/for requested resource
Response field “message” may contain additional information about error.
Contents
- SFA API
- API basics
- General functions
- Item functions
- action - create unit control action
- action_toggle - toggle unit status
- disable_actions - disable unit actions
- enable_actions - enable unit actions
- groups - get item group list
- kill - kill unit actions
- q_clean - clean action queue of unit
- result - get action status or macro run result
- state - get item state
- state_history - get item state history
- terminate - terminate action execution
- clear - clear lvar state
- reset - reset lvar state
- set - set lvar state
- toggle - clear lvar state
- LVar functions
- Logic control macros
- Logic cycles
- Remote controllers
- append_controller - connect remote controller via HTTP
- disable_controller - disable connected controller
- enable_controller - enable connected controller
- get_controller - get connected controller information
- list_controller_props - get controller connection parameters
- list_controllers - get controllers list
- list_remote - get a list of items from connected controllers
- matest_controller - test management API connection to remote controller
- reload_controller - reload controller
- remove_controller - disconnect controller
- set_controller_prop - set controller connection parameters
- test_controller - test connection to remote controller
- Connected clients
General functions
test - test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
POST /sfa-api/test HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/test -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/test --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/test Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/test', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"cloud_manager": true,
"db_update": 1,
"debug": true,
"file_management": true,
"polldelay": 0.01,
"product_build": 2019032301,
"product_code": "sfa",
"product_name": "EVA SCADA Final Aggregator",
"result": "OK",
"setup_mode": false,
"system": "mws1-v1",
"time": 1553393178.4677293,
"uptime": 2,
"version": "3.2.0"
}
Parameters:
- k any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
login - log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /sfa-api/login HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8828/sfa-api/login -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8828/sfa-api/login --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8828/sfa-api/login Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/login', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- k valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
logout - log out and purge authentication token
Purges authentication token
http
POST /sfa-api/logout HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7" }
curl
curl -i -X POST http://localhost:8812/sfa-api/logout -H 'Content-Type: application/json' --data-raw '{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
wget
wget -S -O- http://localhost:8812/sfa-api/logout --header='Content-Type: application/json' --post-data='{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
httpie
echo '{
"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
}' | http POST http://localhost:8812/sfa-api/logout Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sfa-api/logout', headers={
'Content-Type': 'application/json',
}, json={
'k': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid token
Item functions
action - create unit control action
The call is considered successful when action is put into the action queue of selected unit.
http
POST /sfa-api/action HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1", "s": 1 }
curl
curl -i -X POST http://localhost:8828/sfa-api/action -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey", "s": 1}'
wget
wget -S -O- http://localhost:8828/sfa-api/action --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey", "s": 1}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey",
"s": 1
}' | http POST http://localhost:8828/sfa-api/action Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/action', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
's': 1,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0005889,
"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": 1559868835.75104,
"pending": 1559868835.751197,
"refused": 1559868835.7516289
},
"uuid": "d2aab822-ec47-4370-8145-f8f455db4d27"
}
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 /sfa-api/action_toggle HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/action_toggle -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/action_toggle --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/action_toggle Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/action_toggle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.001091,
"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": 1559868835.7902575,
"pending": 1559868835.7906036,
"refused": 1559868835.7913485
},
"uuid": "8038de65-3833-4aa5-94c1-c0f0e86eb3fe"
}
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 /sfa-api/disable_actions HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/disable_actions -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/disable_actions --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/disable_actions Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/disable_actions', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
enable_actions - enable unit actions
Enables unit to run and queue new actions.
http
POST /sfa-api/enable_actions HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/enable_actions -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/enable_actions --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/enable_actions Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/enable_actions', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
groups - get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
POST /sfa-api/groups HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "p": "unit" }
curl
curl -i -X POST http://localhost:8828/sfa-api/groups -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "unit"}'
wget
wget -S -O- http://localhost:8828/sfa-api/groups --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "unit"}'
httpie
echo '{
"k": "mykey",
"p": "unit"
}' | http POST http://localhost:8828/sfa-api/groups Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/groups', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'unit',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"mb",
"room1",
"tests"
]
Parameters:
- k valid API key
- p item type (unit [U], sensor [S] or lvar [LV])
kill - kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
http
POST /sfa-api/kill HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/kill -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/kill --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/kill Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/kill', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"pt": "denied",
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
Returns:
If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)
q_clean - clean action queue of unit
Cancels all queued actions, keeps the current action running.
http
POST /sfa-api/q_clean HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/q_clean -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/q_clean --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/q_clean Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/q_clean', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i unit id
result - get action status or macro run result
Checks the result of the action by its UUID or returns the actions for the specified unit or execution result of the specified macro.
http
POST /sfa-api/result HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/result -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/result --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/result Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/result', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0006144,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0452583,
"pending": 1559868829.0455182,
"refused": 1559868829.0458727
},
"uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0010161,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.087297,
"pending": 1559868829.0876813,
"refused": 1559868829.088313
},
"uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0005889,
"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": 1559868835.75104,
"pending": 1559868835.751197,
"refused": 1559868835.7516289
},
"uuid": "d2aab822-ec47-4370-8145-f8f455db4d27"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.001091,
"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": 1559868835.7902575,
"pending": 1559868835.7906036,
"refused": 1559868835.7913485
},
"uuid": "8038de65-3833-4aa5-94c1-c0f0e86eb3fe"
}
]
Parameters:
- k valid API key
Optionally:
- u action uuid or
- i unit/macro oid (either uuid or oid must be specified)
- 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
state - get item state
State of the item or all items of the specified type can be obtained using state command.
http
POST /sfa-api/state HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "p": "sensor" }
curl
curl -i -X POST http://localhost:8828/sfa-api/state -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "sensor"}'
wget
wget -S -O- http://localhost:8828/sfa-api/state --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "sensor"}'
httpie
echo '{
"k": "mykey",
"p": "sensor"
}' | http POST http://localhost:8828/sfa-api/state Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/state', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
'p': 'sensor',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "uc/mws1-v1",
"full_id": "env/temp_test",
"group": "env",
"id": "temp_test",
"oid": "sensor:env/temp_test",
"status": 1,
"type": "sensor",
"value": "191"
},
{
"controller_id": "uc/mws1-v1",
"full_id": "room1/lamps",
"group": "room1",
"id": "lamps",
"oid": "sensor:room1/lamps",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"controller_id": "uc/mws1-v1",
"full_id": "room2/h",
"group": "room2",
"id": "h",
"oid": "sensor:room2/h",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"controller_id": "uc/mws1-v1",
"full_id": "room2/lamps",
"group": "room2",
"id": "lamps",
"oid": "sensor:room2/lamps",
"status": 0,
"type": "sensor",
"value": "null"
}
]
Parameters:
- k valid API key
- p item type (unit [U], sensor [S] or lvar [LV])
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.
http
POST /sfa-api/state_history HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "sensor:env/temp_test" }
curl
curl -i -X POST http://localhost:8828/sfa-api/state_history -H 'Content-Type: application/json' --data-raw '{"i": "sensor:env/temp_test", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/state_history --header='Content-Type: application/json' --post-data='{"i": "sensor:env/temp_test", "k": "mykey"}'
httpie
echo '{
"i": "sensor:env/temp_test",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/state_history Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/state_history', headers={
'Content-Type': 'application/json',
}, json={
'i': 'sensor:env/temp_test',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"status": [
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1
],
"t": [
1553390125.8643427,
1553390140.929797,
1553390334.862889,
1553390589.4016967,
1553390732.9677052,
1553391169.14625,
1553391188.7430675,
1553391215.390878,
1553391623.3912942,
1553391746.352703,
1553391851.0065582,
1553391951.145705,
1553391968.589165,
1553392069.766155,
1553392157.956836,
1553392366.729588,
1553392495.9142005,
1553392581.9080076,
1553393041.2446685,
1553393176.3235447
],
"value": [
19.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0
]
}
Parameters:
- k valid API key
- a history notifier id (default: db_1)
- i item oids or full ids, list or comma separated
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
- g output format (“list”, “dict” or “chart”, default is “list”)
- c options for chart (dict or comma separated)
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
- type: chart type (line or bar, default is line)
- tf: chart time format
- out: output format (svg, png, default is svg),
- style: chart style (without “Style” suffix, e.g. Dark)
- other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
terminate - terminate action execution
Terminates or cancel the action if it is still queued
http
POST /sfa-api/terminate HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "unit:tests/unit1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/terminate -H 'Content-Type: application/json' --data-raw '{"i": "unit:tests/unit1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/terminate --header='Content-Type: application/json' --post-data='{"i": "unit:tests/unit1", "k": "mykey"}'
httpie
echo '{
"i": "unit:tests/unit1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/terminate Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/terminate', headers={
'Content-Type': 'application/json',
}, json={
'i': 'unit:tests/unit1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- u action uuid or
- i unit id
Returns:
An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)
clear - clear lvar state
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.
http
POST /sfa-api/clear HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/clear -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/clear --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/clear Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/clear', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
reset - reset lvar state
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.
http
POST /sfa-api/reset HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/reset -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/reset --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/reset Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/reset', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
set - set lvar state
Set status and value of a logic variable.
http
POST /sfa-api/set HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1", "s": 1, "v": 29 }
curl
curl -i -X POST http://localhost:8828/sfa-api/set -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey", "s": 1, "v": 29}'
wget
wget -S -O- http://localhost:8828/sfa-api/set --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey", "s": 1, "v": 29}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey",
"s": 1,
"v": 29
}' | http POST http://localhost:8828/sfa-api/set Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/set', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
's': 1,
'v': 29,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
Optionally:
- s lvar status
- v lvar value
toggle - clear lvar state
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.
http
POST /sfa-api/toggle HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/toggle -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/toggle --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/toggle Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/toggle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
LVar functions
decrement - decrement lvar value
Decrement value of a logic variable. Initial value should be number
http
POST /sfa-api/decrement HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/decrement -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/decrement --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/decrement Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/decrement', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
increment - increment lvar value
Increment value of a logic variable. Initial value should be number
http
POST /sfa-api/increment HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/lvar1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/increment -H 'Content-Type: application/json' --data-raw '{"i": "tests/lvar1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/increment --header='Content-Type: application/json' --post-data='{"i": "tests/lvar1", "k": "mykey"}'
httpie
echo '{
"i": "tests/lvar1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/increment Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/increment', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/lvar1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k valid API key
- i lvar id
Logic control macros
groups_macro - get macro groups list
Get the list of macros. Useful e.g. for custom interfaces.
http
POST /sfa-api/groups_macro HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/groups_macro -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/groups_macro --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/groups_macro Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/groups_macro', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"nogroup",
"tests"
]
Parameters:
- k valid API key
list_macros - get macro list
Get the list of all available macros.
http
POST /sfa-api/list_macros HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/list_macros -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/list_macros --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/list_macros Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/list_macros', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "nogroup/lr",
"group": "nogroup",
"id": "lr",
"oid": "lmacro:nogroup/lr",
"type": "lmacro"
},
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "test macro",
"full_id": "tests/test",
"group": "tests",
"id": "test",
"oid": "lmacro:tests/test",
"type": "lmacro"
},
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/test1",
"group": "tests",
"id": "test1",
"oid": "lmacro:tests/test1",
"type": "lmacro"
},
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/test2",
"group": "tests",
"id": "test2",
"oid": "lmacro:tests/test2",
"type": "lmacro"
}
]
Parameters:
- k valid API key
Optionally:
- g filter by group
- i filter by controller
run - execute macro
Execute a macro with the specified arguments.
http
POST /sfa-api/run HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/test1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/run -H 'Content-Type: application/json' --data-raw '{"i": "tests/test1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/run --header='Content-Type: application/json' --post-data='{"i": "tests/test1", "k": "mykey"}'
httpie
echo '{
"i": "tests/test1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/run Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/run', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/test1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"args": [],
"err": "",
"exitcode": null,
"finished": false,
"finished_in": null,
"item_group": "tests",
"item_id": "test1",
"item_oid": "lmacro:tests/test1",
"item_type": "lmacro",
"kwargs": {},
"out": "",
"priority": 100,
"status": "running",
"time": {
"created": 1559868836.2586453,
"pending": 1559868836.258813,
"queued": 1559868836.2594464,
"running": 1559868836.2602909
},
"uuid": "d7ced6b4-f0fc-4b11-8e4c-c2960ca8617e"
}
Parameters:
- k valid API key
- i macro id
Optionally:
- a macro arguments, array or space separated
- kw macro keyword arguments, name=value, comma separated or dict
- 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”
Logic cycles
get_cycle - get cycle information
http
POST /sfa-api/get_cycle HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "tests/cycle1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/get_cycle -H 'Content-Type: application/json' --data-raw '{"i": "tests/cycle1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/get_cycle --header='Content-Type: application/json' --post-data='{"i": "tests/cycle1", "k": "mykey"}'
httpie
echo '{
"i": "tests/cycle1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/get_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/get_cycle', headers={
'Content-Type': 'application/json',
}, json={
'i': 'tests/cycle1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"id": "cycle1",
"interval": 0.01,
"oid": "lcycle:tests/cycle1",
"type": "lcycle"
}
Parameters:
- k valid API key
- i cycle id
Returns:
field “value” contains real average cycle interval
groups_cycle - get cycle groups list
Get the list of cycles. Useful e.g. for custom interfaces.
http
POST /sfa-api/groups_cycle HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/groups_cycle -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/groups_cycle --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/groups_cycle Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/groups_cycle', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"tests"
]
Parameters:
- k valid API key
list_cycles - get cycle list
Get the list of all available cycles.
http
POST /sfa-api/list_cycles HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/list_cycles -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/list_cycles --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/list_cycles Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/list_cycles', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"id": "cycle1",
"interval": 0.01,
"oid": "lcycle:tests/cycle1",
"status": 0,
"type": "lcycle",
"value": "0,0.0100,"
},
{
"controller_id": "lm/mws1-v1",
"description": "test 2Hz cycle",
"full_id": "tests/test1",
"group": "tests",
"id": "test1",
"interval": 0.5,
"oid": "lcycle:tests/test1",
"status": 0,
"type": "lcycle",
"value": "0,0.5000,"
}
]
Parameters:
- k valid API key
Optionally:
- g filter by group
- i filter by controller
Remote controllers
append_controller - connect remote controller via HTTP
Connects remote controller to the local.
http
POST /sfa-api/append_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "u": "localhost", "a": "secretkey", "g": "uc", "save": true }
curl
curl -i -X POST http://localhost:8828/sfa-api/append_controller -H 'Content-Type: application/json' --data-raw '{"a": "secretkey", "g": "uc", "k": "mykey", "save": true, "u": "localhost"}'
wget
wget -S -O- http://localhost:8828/sfa-api/append_controller --header='Content-Type: application/json' --post-data='{"a": "secretkey", "g": "uc", "k": "mykey", "save": true, "u": "localhost"}'
httpie
echo '{
"a": "secretkey",
"g": "uc",
"k": "mykey",
"save": true,
"u": "localhost"
}' | http POST http://localhost:8828/sfa-api/append_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/append_controller', headers={
'Content-Type': 'application/json',
}, json={
'a': 'secretkey',
'g': 'uc',
'k': 'mykey',
'save': True,
'u': 'localhost',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- k API key with master permissions
- u Controller API uri (proto://host:port, port not required if default)
- a remote controller API key ($key to use local key)
Optionally:
- m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)
- s verify remote SSL certificate or pass invalid
- t timeout (seconds) for the remote controller API calls
- g controller type (“uc” or “lm”), autodetected if none
- save save connected controller configuration on the disk immediately after creation
disable_controller - disable connected controller
http
POST /sfa-api/disable_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1", "save": true }
curl
curl -i -X POST http://localhost:8828/sfa-api/disable_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8828/sfa-api/disable_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8828/sfa-api/disable_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/disable_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
Optionally:
- save save configuration after successful call
enable_controller - enable connected controller
http
POST /sfa-api/enable_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1", "save": true }
curl
curl -i -X POST http://localhost:8828/sfa-api/enable_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8828/sfa-api/enable_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey", "save": true}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey",
"save": true
}' | http POST http://localhost:8828/sfa-api/enable_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/enable_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
'save': True,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
Optionally:
- save save configuration after successful call
get_controller - get connected controller information
http
POST /sfa-api/get_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/get_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/get_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/get_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/get_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- k API key with master permissions
- i controller id
list_controller_props - get controller connection parameters
http
POST /sfa-api/list_controller_props HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/list_controller_props -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/list_controller_props --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/list_controller_props Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/list_controller_props', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"key": "secretkey",
"mqtt_update": null,
"reload_interval": 300,
"retries": 2,
"ssl_verify": true,
"static": true,
"timeout": 5.0,
"uri": "http://localhost:8812"
}
Parameters:
- k API key with master permissions
- i controller id
list_controllers - get controllers list
Get the list of all connected controllers.
http
POST /sfa-api/list_controllers HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/list_controllers -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/list_controllers --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/list_controllers Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/list_controllers', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"build": "2019032301",
"connected": true,
"description": "",
"enabled": true,
"full_id": "lm/mws1-v1",
"group": "lm",
"id": "mws1-v1",
"managed": false,
"mqtt_update": "eva_1",
"oid": "remote_lm:lm/mws1-v1",
"proto": "http",
"static": true,
"type": "remote_lm",
"version": "3.2.0"
},
{
"build": "2019032301",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/mws1-v1",
"group": "uc",
"id": "mws1-v1",
"managed": false,
"mqtt_update": "eva_1",
"oid": "remote_uc:uc/mws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
]
Parameters:
- k API key with master permissions
- g filter by group (“uc” or “lm”)
list_remote - get a list of items from connected controllers
Get a list of the items loaded from the connected controllers. Useful to debug the controller connections.
http
POST /sfa-api/list_remote HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/list_remote -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/list_remote --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/list_remote Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/list_remote', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "env/temp_test",
"group": "env",
"id": "temp_test",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"oid": "sensor:env/temp_test",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"action_enabled": true,
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "nogroup/test2",
"group": "nogroup",
"id": "test2",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"nstatus": -1,
"nvalue": "null",
"oid": "unit:nogroup/test2",
"status": -1,
"status_labels": [
{
"label": "OFF",
"status": 0
},
{
"label": "ON",
"status": 1
}
],
"type": "unit",
"value": "null"
}
]
Parameters:
- k API key with master permissions
Optionally:
- i controller id
- g filter by item group
- p filter by item type
matest_controller - test management API connection to remote controller
http
POST /sfa-api/matest_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/matest_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/matest_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/matest_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/matest_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
reload_controller - reload controller
Reloads items from connected controller. If controller ID “ALL” is specified, all connected controllers are reloaded.
http
POST /sfa-api/reload_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/reload_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/reload_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/reload_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/reload_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
remove_controller - disconnect controller
http
POST /sfa-api/remove_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/remove_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/remove_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/remove_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/remove_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
set_controller_prop - set controller connection parameters
http
POST /sfa-api/set_controller_prop HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1", "p": "reload_interval", "v": 60, "save": true }
curl
curl -i -X POST http://localhost:8828/sfa-api/set_controller_prop -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey", "p": "reload_interval", "save": true, "v": 60}'
wget
wget -S -O- http://localhost:8828/sfa-api/set_controller_prop --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey", "p": "reload_interval", "save": true, "v": 60}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey",
"p": "reload_interval",
"save": true,
"v": 60
}' | http POST http://localhost:8828/sfa-api/set_controller_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/set_controller_prop', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
'p': 'reload_interval',
'save': True,
'v': 60,
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller 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_controller - test connection to remote controller
http
POST /sfa-api/test_controller HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey", "i": "uc/ws1-v1" }
curl
curl -i -X POST http://localhost:8828/sfa-api/test_controller -H 'Content-Type: application/json' --data-raw '{"i": "uc/ws1-v1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/test_controller --header='Content-Type: application/json' --post-data='{"i": "uc/ws1-v1", "k": "mykey"}'
httpie
echo '{
"i": "uc/ws1-v1",
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/test_controller Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/test_controller', headers={
'Content-Type': 'application/json',
}, json={
'i': 'uc/ws1-v1',
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i controller id
Connected clients
notify_restart - notify connected clients about server restart
Sends a server restart event to all connected clients asking them to prepare for server restart.
All the connected clients receive the event with subject=”server” and data=”restart”. If the clients use EVA JS Framework, they can catch server.restart event.
Server restart notification is sent automatically to all connected clients when the server is restarting. This API function allows to send server restart notification without actual server restart, which may be useful e.g. for testing, handling frontend restart etc.
http
POST /sfa-api/notify_restart HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/notify_restart -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/notify_restart --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/notify_restart Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/notify_restart', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
reload_clients - ask connected clients to reload
Sends reload event to all connected clients asking them to reload the interface.
All the connected clients receive the event with subject=”reload” and data=”asap”. If the clients use EVA JS Framework, they can catch server.reload event.
http
POST /sfa-api/reload_clients HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8828/sfa-api/reload_clients -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8828/sfa-api/reload_clients --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8828/sfa-api/reload_clients Content-Type:application/json
python-requests
requests.post('http://localhost:8828/sfa-api/reload_clients', headers={
'Content-Type': 'application/json',
}, json={
'k': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
UC RESTful API
Universal Controller API is used to control and manage units and sensors
This document describes API methods for RESTful calls. For direct and JSON RPC calls look UC API.
RESTful API basics
Majority EVA ICS API components and items support REST. Parameters for POST, PUT, PATCH and DELETE requests can be sent in both JSON and multipart/form-data. For JSON, Content-Type: application/json header must be specified.
Long API calls
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Requests
API key can be sent in HTTP X-Auth-Key header (preferred) or in request parameters (as k).
- GET request is used to get information about resource or list of resources of the specified type.
- POST request is used to perform special API calls and create resources in case when resource id is generated by server. In the last case, response always contains additional field Location which points to the resource created.
- PUT request is used to create new resources. If resource already exists, the server could refuse recreating it, responding with 409 Conflict HTTP error.
- PATCH request is used to modify resource parameters.
- DELETE request is used to delete resource.
For resource creation and modification, multiple parameters can be specified in a single request. For majority requests of such purpose, a special parameter “save” is used to tell server (if “save”: true) to save the resource configuration immediately after its modification.
For the group-related calls, put trailing slash at the end of the request URL:
/r/<resource_type>/<group>/
Responses
Success responses:
- 200 OK API call completed successfully
- 201 Created API call completed successfully, Response header Location contains either uri to the newly created object or resource is accessible by the effective request uri. For resources created with PUT, body contains either serialized resource object or resource type and id
- 202 Accepted The server accepted command and will process it later.
- 204 No Content API call completed successfully, no content to return
Error responses:
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found resource doesn’t exist
- 405 Method Not Allowed API function/method not found
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
Response body may contain additional information encoded in JSON. { “result”: “OK” } and { “result”: “ERROR” } in body are not returned.
Contents
- UC RESTful API
- RESTful API basics
- General functions
- Item functions
- clean action queue of unit
- disable unit actions
- enable unit actions
- get action status
- get item group list
- get item state
- get item state history
- kill unit actions
- start item maintenance mode
- stop item maintenance mode
- terminate action execution
- toggle unit status
- unit control action
- update the status and value of the item
- Item management
- 1-Wire bus via OWFS
- Modbus ports
- Physical interfaces (PHIs)
- delete PHI module file
- discover installed equipment supported by PHI module
- execute additional PHI commands
- get PHI module info
- get PHI usage help
- get list of PHI ports
- get list of available PHI modules
- list loaded PHIs
- load PHI module
- set PHI configuration property
- test PHI
- unload PHI
- upload PHI module
- LPI and drivers
- Devices
- CVARs
- Locking functions
- Logging
- API keys
- User accounts
- Notifier management
- File management
General functions
test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
GET /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/core -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/core --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/core X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/core', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"db_update": 1,
"debug": true,
"file_management": true,
"layout": "enterprise",
"polldelay": 0.001,
"product_build": 2019031405,
"product_code": "uc",
"product_name": "EVA Universal Controller",
"setup_mode": false,
"system": "mws1-v1",
"time": 1552867566.880533,
"uptime": 990,
"version": "3.2.0"
}
Parameters:
- API Key any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
save database and runtime configuration
All modified items, their status, and configuration will be written to the disk. If exec_before_save command is defined in the controller’s configuration file, it’s called before saving and exec_after_save after (e.g. to switch the partition to write mode and back to read-only).
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'
httpie
echo '{
"method": "save"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'save',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
execute a remote system command
Executes a command script on the server where the controller is installed.
http
POST /r/cmd/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "0 2 3", "w": 5, "t": 10 }
curl
curl -i -X POST http://localhost:8812/r/cmd/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "0 2 3", "t": 10, "w": 5}'
wget
wget -S -O- http://localhost:8812/r/cmd/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "0 2 3", "t": 10, "w": 5}'
httpie
echo '{
"a": "0 2 3",
"t": 10,
"w": 5
}' | http POST http://localhost:8812/r/cmd/test Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/cmd/test', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': '0 2 3',
't': 10,
'w': 5,
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"args": [
"0",
"2",
"3"
],
"cmd": "test",
"err": "some text to stderr\n",
"exitcode": 0,
"out": "test script start\nparam 1: 0 ( > 0 will generate \"failed\" status)\nparam 2: 2\nparam 3: 3\ndelay 3 sec\nscript finish\n",
"status": "completed",
"time": {
"completed": 1552863480.7081513,
"created": 1552863480.6993306,
"running": 1552863480.7001197
},
"timeout": 10.0
}
Parameters:
- API Key API key with allow=cmd permissions
Optionally:
- a string of command arguments, separated by spaces (passed to the script)
- w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "shutdown" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "shutdown"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "shutdown"}'
httpie
echo '{
"method": "shutdown"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'shutdown',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
switch debugging mode
Enables and disables debugging mode while the controller is running. After the controller is restarted, this parameter is lost and controller switches back to the mode specified in the configuration file.
http
PATCH /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "debug": true }
curl
curl -i -X PATCH http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"debug": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"debug": true}'
httpie
echo '{
"debug": true
}' | http PATCH http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'debug': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- debug true for enabling debug mode, false for disabling
log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /r/token HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8812/r/token -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8812/r/token --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8812/r/token Content-Type:application/json
python-requests
requests.post('http://localhost:8812/r/token', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- API Key valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
log out and purge authentication token
Purges authentication token
http
DELETE /r/token HTTP/1.1
Host: localhost:8812
X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
curl
curl -i -X DELETE http://localhost:8812/r/token -H 'X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/token --header='X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'
httpie
http DELETE http://localhost:8812/r/token X-Auth-Key:token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
python-requests
requests.delete('http://localhost:8812/r/token', headers={
'X-Auth-Key': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid token
Item functions
clean action queue of unit
Cancels all queued actions, keeps the current action running.
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "q_clean" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "q_clean"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "q_clean"}'
httpie
echo '{
"method": "q_clean"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'q_clean',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
disable unit actions
Disables unit to run and queue new actions.
http
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "action_enabled": false }
curl
curl -i -X PATCH http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": false}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": false}'
httpie
echo '{
"action_enabled": false
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'action_enabled': False,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
enable unit actions
Enables unit to run and queue new actions.
http
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "action_enabled": true }
curl
curl -i -X PATCH http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": true}'
httpie
echo '{
"action_enabled": true
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'action_enabled': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
get action status
Checks the result of the action by its UUID or returns the actions for the specified unit.
http
GET /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/action -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/action --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/action X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/action', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0006144,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0452583,
"pending": 1559868829.0455182,
"refused": 1559868829.0458727
},
"uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
},
{
"err": "",
"exitcode": -15,
"finished": true,
"finished_in": 1.301712,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "terminated",
"time": {
"created": 1559868829.0540679,
"pending": 1559868829.054227,
"queued": 1559868829.05472,
"running": 1559868829.0551677,
"terminated": 1559868830.35578
},
"uuid": "18bcbf97-d35d-4f18-8354-d18d092df5f7"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0010161,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.087297,
"pending": 1559868829.0876813,
"refused": 1559868829.088313
},
"uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.000658,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0973055,
"pending": 1559868829.0975406,
"refused": 1559868829.0979636
},
"uuid": "17570e18-03ca-4772-8665-90af574325b9"
}
]
Parameters:
- API Key valid API key
Optionally:
- g filter by unit group
- s filter by action status: Q for queued, R for running, F for finished
Returns:
list or single serialized action object
get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
GET /r/unit/@groups HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/unit/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/unit/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/unit/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/unit/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"room1",
"test_device_5",
"test_device_7",
"tests"
]
Parameters:
- API Key valid API key
get item state
State of the item or all items of the specified type can be obtained using state command.
http
GET /r/sensor HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/sensor -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/sensor --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/sensor X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/sensor', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"full_id": "tests/sensor1",
"group": "tests",
"id": "sensor1",
"oid": "sensor:tests/sensor1",
"status": 1,
"type": "sensor",
"value": 29.445
},
{
"full_id": "tests/sensor2",
"group": "tests",
"id": "sensor2",
"oid": "sensor:tests/sensor2",
"status": 1,
"type": "sensor",
"value": 29.445
}
]
Parameters:
- API Key valid API key
Optionally:
get item state history
State history of one item or several items of the specified type can be obtained using state_history command.
http
GET /r/sensor/tests/sensor2@history HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/sensor/tests/sensor2@history -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/sensor/tests/sensor2@history --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/sensor/tests/sensor2@history X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/sensor/tests/sensor2@history', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"status": [
null,
null,
1,
null,
1
],
"t": [
1552865635.6868849,
1552866234.5211835,
1552866297.7497892,
1552866495.7593722,
1552866511.8293397,
1552866513.8805466
],
"value": [
29.445,
29.42,
28,
29.11,
29.42,
29.441
]
}
Parameters:
- API Key valid API key
- a history notifier id (default: db_1)
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
- g output format (“list”, “dict” or “chart”, default is “list”)
- c options for chart (dict or comma separated)
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
- type: chart type (line or bar, default is line)
- tf: chart time format
- out: output format (svg, png, default is svg),
- style: chart style (without “Style” suffix, e.g. Dark)
- other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "kill" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "kill"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "kill"}'
httpie
echo '{
"method": "kill"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'kill',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Returns:
If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)
start item maintenance mode
During maintenance mode all item updates are ignored, however actions still can be executed
http
PATCH /r/sensor/tests/sensor1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "maintenance": true }
curl
curl -i -X PATCH http://localhost:8812/r/sensor/tests/sensor1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"maintenance": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/sensor/tests/sensor1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"maintenance": true}'
httpie
echo '{
"maintenance": true
}' | http PATCH http://localhost:8812/r/sensor/tests/sensor1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/sensor/tests/sensor1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'maintenance': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key masterkey
stop item maintenance mode
http
PATCH /r/sensor/tests/sensor1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "maintenance": false }
curl
curl -i -X PATCH http://localhost:8812/r/sensor/tests/sensor1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"maintenance": false}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/sensor/tests/sensor1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"maintenance": false}'
httpie
echo '{
"maintenance": false
}' | http PATCH http://localhost:8812/r/sensor/tests/sensor1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/sensor/tests/sensor1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'maintenance': False,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key masterkey
terminate action execution
Terminates or cancel the action if it is still queued
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "terminate" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "terminate"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "terminate"}'
httpie
echo '{
"method": "terminate"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'terminate',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Returns:
An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)
toggle unit status
Create unit control action to toggle its status (1->0, 0->1)
http
POST /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "i": "unit:tests/unit3", "s": "toggle" }
curl
curl -i -X POST http://localhost:8812/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": "toggle"}'
wget
wget -S -O- http://localhost:8812/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": "toggle"}'
httpie
echo '{
"i": "unit:tests/unit3",
"s": "toggle"
}' | http POST http://localhost:8812/r/action Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/action', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'i': 'unit:tests/unit3',
's': 'toggle',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/17570e18-03ca-4772-8665-90af574325b9
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.000658,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0973055,
"pending": 1559868829.0975406,
"refused": 1559868829.0979636
},
"uuid": "17570e18-03ca-4772-8665-90af574325b9"
}
Parameters:
- API Key valid API key
Optionally:
- w wait for the completion for the specified number of seconds
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
unit control action
The call is considered successful when action is put into the action queue of selected unit.
http
POST /r/action HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "s": 1, "i": "unit:tests/unit3", "s": 1 }
curl
curl -i -X POST http://localhost:8812/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": 1}'
wget
wget -S -O- http://localhost:8812/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": 1}'
httpie
echo '{
"i": "unit:tests/unit3",
"s": 1
}' | http POST http://localhost:8812/r/action Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/action', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'i': 'unit:tests/unit3',
's': 1,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/18bcbf97-d35d-4f18-8354-d18d092df5f7
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": false,
"finished_in": null,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "running",
"time": {
"created": 1559868829.0540679,
"pending": 1559868829.054227,
"queued": 1559868829.05472,
"running": 1559868829.0551677
},
"uuid": "18bcbf97-d35d-4f18-8354-d18d092df5f7"
}
Parameters:
- API Key valid API key
Optionally:
- s desired unit status
- v desired unit value
- w wait for the completion for the specified number of seconds
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
update the status and value of the item
Updates the status and value of the item. This is one of the ways of passive state update, for example with the use of an external controller.
Note
Calling without s and v params will force item to perform passive update requesting its status from update script or driver.
http
POST /r/sensor/tests/sensor2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "s": 1, "v": 29.445 }
curl
curl -i -X POST http://localhost:8812/r/sensor/tests/sensor2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": 1, "v": 29.445}'
wget
wget -S -O- http://localhost:8812/r/sensor/tests/sensor2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": 1, "v": 29.445}'
httpie
echo '{
"s": 1,
"v": 29.445
}' | http POST http://localhost:8812/r/sensor/tests/sensor2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/sensor/tests/sensor2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 1,
'v': 29.445,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Optionally:
- s item status
- v item value
Item management
list items
Parameters:
- API Key API key with master permissions
Optionally:
Returns:
the list of all item available
create multi-update
Creates new multi-update.
http
PUT /r/mu/tests/mu2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "update_timeout": 10, "update_interval": 5 }
curl
curl -i -X PUT http://localhost:8812/r/mu/tests/mu2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "update_interval": 5, "update_timeout": 10}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/mu/tests/mu2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "update_interval": 5, "update_timeout": 10}'
httpie
echo '{
"save": true,
"update_interval": 5,
"update_timeout": 10
}' | http PUT http://localhost:8812/r/mu/tests/mu2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/mu/tests/mu2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'save': True,
'update_interval': 5,
'update_timeout': 10,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"config_changed": false,
"description": "",
"full_id": "tests/mu2",
"group": "tests",
"id": "mu2",
"oid": "mu:tests/mu2",
"status": 0,
"type": "mu",
"value": "null",
"virtual": false
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save multi-update configuration immediately
create new item
Creates new item.
http
PUT /r/sensor/tests/sensor2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "update_timeout": 10, "update_interval": 5 }
curl
curl -i -X PUT http://localhost:8812/r/sensor/tests/sensor2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "update_interval": 5, "update_timeout": 10}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/sensor/tests/sensor2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "update_interval": 5, "update_timeout": 10}'
httpie
echo '{
"save": true,
"update_interval": 5,
"update_timeout": 10
}' | http PUT http://localhost:8812/r/sensor/tests/sensor2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/sensor/tests/sensor2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'save': True,
'update_interval': 5,
'update_timeout': 10,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"config_changed": false,
"description": "",
"full_id": "tests/sensor2",
"group": "tests",
"id": "sensor2",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"oid": "sensor:tests/sensor2",
"status": 0,
"type": "sensor",
"value": "null",
"virtual": false
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save multi-update configuration immediately
create new sensor
Creates new sensor.
http
PUT /r/sensor/tests/sensor7 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "update_timeout": 10, "update_interval": 5 }
curl
curl -i -X PUT http://localhost:8812/r/sensor/tests/sensor7 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "update_interval": 5, "update_timeout": 10}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/sensor/tests/sensor7 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "update_interval": 5, "update_timeout": 10}'
httpie
echo '{
"save": true,
"update_interval": 5,
"update_timeout": 10
}' | http PUT http://localhost:8812/r/sensor/tests/sensor7 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/sensor/tests/sensor7', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'save': True,
'update_interval': 5,
'update_timeout': 10,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"config_changed": false,
"description": "",
"full_id": "tests/sensor7",
"group": "tests",
"id": "sensor7",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"oid": "sensor:tests/sensor7",
"status": 0,
"type": "sensor",
"value": "null",
"virtual": false
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save sensor configuration immediately
create new unit
Creates new unit.
http
PUT /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "update_timeout": 10, "action_enabled": true }
curl
curl -i -X PUT http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": true, "save": true, "update_timeout": 10}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": true, "save": true, "update_timeout": 10}'
httpie
echo '{
"action_enabled": true,
"save": true,
"update_timeout": 10
}' | http PUT http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'action_enabled': True,
'save': True,
'update_timeout': 10,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"config_changed": false,
"description": "",
"full_id": "tests/unit3",
"group": "tests",
"id": "unit3",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"nstatus": 0,
"nvalue": "null",
"oid": "unit:tests/unit3",
"status": 0,
"status_labels": [
{
"label": "OFF",
"status": 0
},
{
"label": "ON",
"status": 1
}
],
"type": "unit",
"value": "null",
"virtual": false
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save unit configuration immediately
delete item or group
Deletes the item or the group (and all the items in it) from the system.
http
DELETE /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/unit/tests/unit3 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/unit/tests/unit3 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/unit/tests/unit3 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/unit/tests/unit3', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get item configuration
http
GET /r/unit/tests/unit3@config HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/unit/tests/unit3@config -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit3@config --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/unit/tests/unit3@config X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/unit/tests/unit3@config', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/unit3",
"group": "tests",
"id": "unit3",
"oid": "unit:tests/unit3",
"type": "unit",
"update_timeout": 10.0
}
Parameters:
- API Key API key with master permissions
Returns:
complete item configuration
list item properties
Get all editable parameters of the item confiugration.
http
GET /r/unit/tests/unit1@props HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/unit/tests/unit1@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit1@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/unit/tests/unit1@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/unit/tests/unit1@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_allow_termination": false,
"action_always_exec": false,
"action_driver_config": null,
"action_enabled": true,
"action_exec": null,
"action_queue": 0,
"action_timeout": null,
"auto_off": 0,
"description": "",
"expires": 0,
"location": null,
"mqtt_control": null,
"mqtt_update": null,
"snmp_trap": null,
"status_labels": {
"0": "OFF",
"1": "ON"
},
"term_kill_interval": null,
"update_delay": 0,
"update_driver_config": null,
"update_exec": null,
"update_exec_after_action": false,
"update_if_action": false,
"update_interval": 0,
"update_state_after_action": true,
"update_timeout": null,
"virtual": false
}
Parameters:
- API Key API key with master permissions
save item configuration
Saves item. configuration on disk (even if it hasn’t been changed)
http
POST /r/unit/tests/unit1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/unit1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'
httpie
echo '{
"method": "save"
}' | http POST http://localhost:8812/r/unit/tests/unit1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/unit1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'save',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
set item property
Set configuration parameters of the item.
http
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "action_allow_termination": true, "action_timeout": 10, "update_interval": 10 }
curl
curl -i -X PATCH http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_allow_termination": true, "action_timeout": 10, "update_interval": 10}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_allow_termination": true, "action_timeout": 10, "update_interval": 10}'
httpie
echo '{
"action_allow_termination": true,
"action_timeout": 10,
"update_interval": 10
}' | http PATCH http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'action_allow_termination': True,
'action_timeout': 10,
'update_interval': 10,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
clone group
Creates a copy of all items from the group.
http
POST /r/unit/tests/ HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "clone", "n": "clone_tests" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/ -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "clone", "n": "clone_tests"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/ --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "clone", "n": "clone_tests"}'
httpie
echo '{
"method": "clone",
"n": "clone_tests"
}' | http POST http://localhost:8812/r/unit/tests/ Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'clone',
'n': 'clone_tests',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- n new group to clone to
Optionally:
- p item ID prefix, e.g. device1. for device1.temp1, device1.fan1
- r iem ID prefix in the new group, e.g. device2 (both prefixes must be specified)
- save save configuration immediately
clone item
Creates a copy of the item.
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "clone", "n": "tests/clone_of_unit3" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "clone", "n": "tests/clone_of_unit3"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "clone", "n": "tests/clone_of_unit3"}'
httpie
echo '{
"method": "clone",
"n": "tests/clone_of_unit3"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'clone',
'n': 'tests/clone_of_unit3',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/clone_of_unit3",
"group": "tests",
"id": "clone_of_unit3",
"nstatus": 0,
"nvalue": "null",
"oid": "unit:tests/clone_of_unit3",
"status": 0,
"type": "unit",
"value": "null"
}
Parameters:
- API Key API key with master permissions
- n new item id
Optionally:
- save save multi-update configuration immediately
1-Wire bus via OWFS
create OWFS bus
Creates (defines) OWFS bus with the specified configuration.
Parameter “location” (“n”) should contain the connection configuration, e.g. “localhost:4304” for owhttpd or “i2c=/dev/i2c-1:ALL”, “/dev/i2c-0 –w1” for local 1-Wire bus via I2C, depending on type.
http
PUT /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "n": "localhost:4304", "l": true, "t": 1, "r": 5, "d": 0.3, "save": true }
curl
curl -i -X PUT http://localhost:8812/r/owfs/bus1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"d": 0.3, "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/owfs/bus1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"d": 0.3, "l": true, "n": "localhost:4304", "r": 5, "save": true, "t": 1}'
httpie
echo '{
"d": 0.3,
"l": true,
"n": "localhost:4304",
"r": 5,
"save": true,
"t": 1
}' | http PUT http://localhost:8812/r/owfs/bus1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/owfs/bus1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'd': 0.3,
'l': True,
'n': 'localhost:4304',
'r': 5,
'save': True,
't': 1,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.3,
"id": "bus1",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
}
Parameters:
- API Key API key with master permissions
- n OWFS location
Optionally:
- l lock port on operations, which means to wait while OWFS bus is used by other controller thread (driver command)
- t OWFS operations timeout (in seconds, default: default timeout)
- r retry attempts for each operation (default: no retries)
- d delay between bus operations (default: 50ms)
- save save OWFS bus config after creation
Returns:
If bus with the selected ID is already defined, error is not returned and bus is recreated.
delete OWFS bus
Deletes (undefines) OWFS bus.
Note
In some cases deleted OWFS bus located on I2C may lock libow library calls, which require controller restart until you can use (create) the same I2C bus again.
http
DELETE /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/owfs/bus1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/owfs/bus1 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/owfs/bus1 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/owfs/bus1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get OWFS bus configuration
http
GET /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/owfs/bus1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/owfs/bus1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/owfs/bus1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/owfs/bus1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.3,
"id": "bus1",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
}
Parameters:
- API Key API key with master permissions
list OWFS buses
http
GET /r/owfs HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/owfs -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/owfs --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/owfs X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/owfs', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"delay": 0.3,
"id": "bus1",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
},
{
"delay": 0.3,
"id": "bus_local",
"location": "localhost:4304",
"lock": true,
"retries": 5,
"timeout": 1.0
},
{
"delay": 0.05,
"id": "bus_local1",
"location": "localhost:4304",
"lock": false,
"retries": 0,
"timeout": 4.0
},
{
"delay": 0.05,
"id": "test",
"location": "localhost:4304",
"lock": true,
"retries": 0,
"timeout": 4.0
}
]
Parameters:
- API Key API key with master permissions
scan OWFS bus
Scan OWFS bus for connected 1-Wire devices.
http
POST /r/owfs/bus_local HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "scan" }
curl
curl -i -X POST http://localhost:8812/r/owfs/bus_local -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "scan"}'
wget
wget -S -O- http://localhost:8812/r/owfs/bus_local --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "scan"}'
httpie
echo '{
"method": "scan"
}' | http POST http://localhost:8812/r/owfs/bus_local Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/owfs/bus_local', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'scan',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"path": "22.765A2E63339F",
"type": "DS1822"
},
{
"path": "28.4AEC29CDBAAB",
"type": "DS18B20"
},
{
"path": "10.67C6697351FF",
"type": "DS18S20"
},
{
"path": "05.F2FBE3467CC2",
"type": "DS2405"
},
{
"path": "29.54F81BE8E78D",
"type": "DS2408"
}
]
Parameters:
- API Key API key with master permissions
Optionally:
- p specified equipment type (e.g. DS18S20,DS2405), list or comma separated
- a Equipment attributes (e.g. temperature, PIO), list comma separated
- n Equipment path
- has_all Equipment should have all specified attributes
- full obtain all attributes plus values
Returns:
If both “a” and “full” args are specified. the function will examine and values of attributes specified in “a” param. (This will poll “released” bus, even if locking is set up, so be careful with this feature in production environment).
Bus acquire error can be caused in 2 cases:
- bus is locked * owfs resource not initialized (libow or location problem)
test OWFS bus
Verifies OWFS bus checking library initialization status.
http
POST /r/owfs/bus1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "test" }
curl
curl -i -X POST http://localhost:8812/r/owfs/bus1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'
wget
wget -S -O- http://localhost:8812/r/owfs/bus1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'
httpie
echo '{
"method": "test"
}' | http POST http://localhost:8812/r/owfs/bus1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/owfs/bus1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'test',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Modbus ports
create virtual Modbus port
Creates virtual Modbus port with the specified configuration.
Modbus params should contain the configuration of hardware Modbus port. The following hardware port types are supported:
- tcp , udp Modbus protocol implementations for TCP/IP networks. The params should be specified as: <protocol>:<host>[:port], e.g. tcp:192.168.11.11:502
- rtu, ascii, binary Modbus protocol implementations for the local bus connected with USB or serial port. The params should be specified as: <protocol>:<device>:<speed>:<data>:<parity>:<stop> e.g. rtu:/dev/ttyS0:9600:8:E:1
http
PUT /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "udp:192.168.33.33:502", "l": true, "t": 0.5, "r": 3, "d": 0.2, "save": true }
curl
curl -i -X PUT http://localhost:8812/r/modbus/mbp2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"d": 0.2, "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/modbus/mbp2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"d": 0.2, "l": true, "p": "udp:192.168.33.33:502", "r": 3, "save": true, "t": 0.5}'
httpie
echo '{
"d": 0.2,
"l": true,
"p": "udp:192.168.33.33:502",
"r": 3,
"save": true,
"t": 0.5
}' | http PUT http://localhost:8812/r/modbus/mbp2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/modbus/mbp2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'd': 0.2,
'l': True,
'p': 'udp:192.168.33.33:502',
'r': 3,
'save': True,
't': 0.5,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.2,
"id": "mbp2",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
}
Parameters:
- API Key API key with master permissions
- p Modbus params
Optionally:
- l lock port on operations, which means to wait while Modbus port is used by other controller thread (driver command)
- t Modbus operations timeout (in seconds, default: default timeout)
- r retry attempts for each operation (default: no retries)
- d delay between virtual port operations (default: 20ms)
- save save Modbus port config after creation
Returns:
If port with the selected ID is already created, error is not returned and port is recreated.
delete virtual Modbus port
Deletes virtual Modbus port.
http
DELETE /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/modbus/mbp2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/modbus/mbp2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/modbus/mbp2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/modbus/mbp2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get virtual Modbus port configuration
http
GET /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/modbus/mbp2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/modbus/mbp2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/modbus/mbp2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/modbus/mbp2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"delay": 0.2,
"id": "mbp2",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
}
Parameters:
- API Key API key with master permissions
list virtual Modbus ports
http
GET /r/modbus HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/modbus -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/modbus --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/modbus X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/modbus', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"delay": 0.2,
"id": "mbp1",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
},
{
"delay": 0.2,
"id": "mbp2",
"lock": true,
"params": "udp:192.168.33.33:502",
"retries": 3,
"timeout": 0.5
},
{
"delay": 0.02,
"id": "test",
"lock": false,
"params": "tcp:192.168.1.1",
"retries": 0,
"timeout": 4.0
}
]
Parameters:
- API Key API key with master permissions
read Modbus register(s) from remote slave
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).
Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15
http
GET /r/modbus/local/1/h10-12,c5-6 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/modbus/local/1/h10-12,c5-6 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/modbus/local/1/h10-12,c5-6 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/modbus/local/1/h10-12,c5-6 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/modbus/local/1/h10-12,c5-6', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"addr": "c5",
"value": 0
},
{
"addr": "c6",
"value": 0
},
{
"addr": "h10",
"value": 25
},
{
"addr": "h11",
"value": 0
},
{
"addr": "h12",
"value": 0
}
]
Parameters:
- API Key API key with master permissions
Optionally:
- t max allowed timeout for the operation
test virtual Modbus port
Verifies virtual Modbus port by calling connect() Modbus client method.
Note
As Modbus UDP doesn’t require a port to be connected, API call always returns success unless the port is locked.
http
POST /r/modbus/mbp2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "test" }
curl
curl -i -X POST http://localhost:8812/r/modbus/mbp2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'
wget
wget -S -O- http://localhost:8812/r/modbus/mbp2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'
httpie
echo '{
"method": "test"
}' | http POST http://localhost:8812/r/modbus/mbp2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/modbus/mbp2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'test',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
write Modbus register(s) to remote slave
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, c - coil).
http
PUT /r/modbus/local/1/h10 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "v": 2522 }
curl
curl -i -X PUT http://localhost:8812/r/modbus/local/1/h10 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": 2522}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/modbus/local/1/h10 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": 2522}'
httpie
echo '{
"v": 2522
}' | http PUT http://localhost:8812/r/modbus/local/1/h10 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/modbus/local/1/h10', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': 2522,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- v register value(s) (integer or hex or list)
Optionally:
- t max allowed timeout for the operation
get Modbus slave data
Get data from Modbus slave memory space
Modbus registers must be specified as list or comma separated memory addresses predicated with register type (h - holding, i - input, c - coil, d - discrete input).
Address ranges can be specified, e.g. h1000-1010,c10-15 will return values of holding registers from 1000 to 1010 and coil registers from 10 to 15
http
GET /r/modbus-slave/h1000-1005,c10-15 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/modbus-slave/h1000-1005,c10-15 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/modbus-slave/h1000-1005,c10-15', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"addr": "c10",
"value": 0
},
{
"addr": "c11",
"value": 0
},
{
"addr": "c12",
"value": 0
},
{
"addr": "c13",
"value": 0
},
{
"addr": "c14",
"value": 0
},
{
"addr": "c15",
"value": 0
},
{
"addr": "h1000",
"value": 0
},
{
"addr": "h1001",
"value": 0
},
{
"addr": "h1002",
"value": 0
},
{
"addr": "h1003",
"value": 0
},
{
"addr": "h1004",
"value": 0
},
{
"addr": "h1005",
"value": 0
}
]
Parameters:
- API Key API key with master permissions
Physical interfaces (PHIs)
delete PHI module file
Deletes PHI module file, if the module is loaded, all its instances should be unloaded first.
http
DELETE /r/phi-module/gpio_power HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/phi-module/gpio_power -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/phi-module/gpio_power --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/phi-module/gpio_power X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/phi-module/gpio_power', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
discover installed equipment supported by PHI module
http
GET /r/phi-module/nanoleaf@discover HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/phi-module/nanoleaf@discover -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/phi-module/nanoleaf@discover --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/phi-module/nanoleaf@discover X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/phi-module/nanoleaf@discover', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Content-Type: application/json
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Length: 411
[
{
"!opt": "cols",
"value": [
"IP",
"Name"
]
},
{
"!load": {
"host": "192.168.25.81"
},
"IP": "192.168.25.81",
"Name": "Nanoleaf Light Panels 54:e2:31"
},
{
"!load": {
"host": "10.90.1.82"
},
"IP": "10.90.1.82",
"Name": "Nanoleaf Light Panels 54:f2:36"
}
]
Parameters:
- API Key API key with master permissions
Optionally:
- x interface to perform discover on
- w max time for the operation
execute additional PHI commands
Execute PHI command and return execution result (as-is). help command returns all available commands.
http
POST /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "update_firmware", "a": "/opt/firmware/fw.dat", "method": "exec" }
curl
curl -i -X POST http://localhost:8812/r/phi/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "method": "exec"}'
wget
wget -S -O- http://localhost:8812/r/phi/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "/opt/firmware/fw.dat", "c": "update_firmware", "method": "exec"}'
httpie
echo '{
"a": "/opt/firmware/fw.dat",
"c": "update_firmware",
"method": "exec"
}' | http POST http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/phi/test1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': '/opt/firmware/fw.dat',
'c': 'update_firmware',
'method': 'exec',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"output": "not implemented"
}
Parameters:
- API Key API key with master permissions
- c command to exec
- a command argument
get PHI module info
http
GET /r/phi-module/vrtrelay HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/phi-module/vrtrelay -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/phi-module/vrtrelay --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/phi-module/vrtrelay X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/phi-module/vrtrelay', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": null,
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
}
Parameters:
- API Key API key with master permissions
get PHI usage help
http
GET /r/phi-module/vrtrelay?help=cfg HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8812/r/phi-module/vrtrelay?help=cfg' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/phi-module/vrtrelay?help=cfg', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"help": "ports status on load (default: -1)",
"name": "default_status",
"required": false,
"type": "int"
},
{
"help": "send updates to items every N sec",
"name": "update",
"required": false,
"type": "float"
}
]
Parameters:
- API Key API key with master permissions
get list of PHI ports
http
GET /r/phi/test1@ports HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/phi/test1@ports -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/phi/test1@ports --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/phi/test1@ports X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/phi/test1@ports', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "virtual relay port #1",
"name": "port #1",
"port": "1"
},
{
"description": "virtual relay port #2",
"name": "port #2",
"port": "2"
},
{
"description": "virtual relay port #3",
"name": "port #3",
"port": "3"
},
{
"description": "virtual relay port #4",
"name": "port #4",
"port": "4"
},
{
"description": "virtual relay port #5",
"name": "port #5",
"port": "5"
},
{
"description": "virtual relay port #6",
"name": "port #6",
"port": "6"
},
{
"description": "virtual relay port #7",
"name": "port #7",
"port": "7"
},
{
"description": "virtual relay port #8",
"name": "port #8",
"port": "8"
},
{
"description": "virtual relay port #9",
"name": "port #9",
"port": "9"
},
{
"description": "virtual relay port #10",
"name": "port #10",
"port": "10"
},
{
"description": "virtual relay port #11",
"name": "port #11",
"port": "11"
},
{
"description": "virtual relay port #12",
"name": "port #12",
"port": "12"
},
{
"description": "virtual relay port #13",
"name": "port #13",
"port": "13"
},
{
"description": "virtual relay port #14",
"name": "port #14",
"port": "14"
},
{
"description": "virtual relay port #15",
"name": "port #15",
"port": "15"
},
{
"description": "virtual relay port #16",
"name": "port #16",
"port": "16"
}
]
Parameters:
- API Key API key with master permissions
get list of available PHI modules
http
GET /r/phi-module HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/phi-module -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/phi-module --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/phi-module X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/phi-module', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "EG-PM2-LAN smart PDU",
"equipment": [
"EG-PM2-LAN"
],
"features": [
"aao_get",
"port_set",
"cache"
],
"help": "\nPHI for Energenie (Gembird) EG-PM2-LAN smart PDU. You may use 'skip_logout'\nparam to let PHI skip logout procedure after the requests. This speed up the\nfunctions however may cause the equipment to be locked to UC IP only.\n",
"id": null,
"license": "https://www.eva-ics.com/license",
"lpi_default": "basic",
"mod": "eg_pm2lan",
"mods_required": [],
"oid": null,
"required": [
"aao_get",
"port_set",
"status",
"action"
],
"version": "1.0.2"
},
{
"api": 3,
"author": "Altertech Group, https://www.altertech.com/",
"description": "1-Wire OWFS universal sensor driver",
"equipment": [
"Any 1-Wire sensor"
],
"features": [
"port_get",
"universal"
],
"help": "\nPHI for Maxim Integrated 1-Wire DS18N20 equipment working via OWFS.\n\nCan be used for various types of sensors as attr (e.g. \"temperature\" or\n\"voltage\") is specified by user. This is unversal PHI, owfs bus, path and attr\ncan be specified in EVA ICS sensor configuration.\n",
"id": null,
"license": "Apache License 2.0",
"lpi_default": "sensor",
"mod": "ow_sensor",
"mods_required": [],
"oid": null,
"required": [
"port_get",
"value"
],
"version": "1.0.0"
}
]
Parameters:
- API Key API key with master permissions
list loaded PHIs
http
GET /r/phi HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/phi -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/phi --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/phi X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/phi', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"id": "test",
"mod": "vrtrelay"
},
{
"id": "test1",
"mod": "vrtrelay"
},
{
"id": "test2",
"mod": "vrtrelay"
}
]
Parameters:
- API Key API key with master permissions
- full get exntended information
load PHI module
Loads Physical Interface.
http
PUT /r/phi/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "vrtrelay", "c": "default_status=0", "save": true }
curl
curl -i -X PUT http://localhost:8812/r/phi/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "default_status=0", "m": "vrtrelay", "save": true}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/phi/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"c": "default_status=0", "m": "vrtrelay", "save": true}'
httpie
echo '{
"c": "default_status=0",
"m": "vrtrelay",
"save": true
}' | http PUT http://localhost:8812/r/phi/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/phi/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'default_status=0',
'm': 'vrtrelay',
'save': True,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 0
},
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"id": "test2",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test2",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
}
Parameters:
- API Key API key with master permissions
- m PHI module
Optionally:
- c PHI configuration
- save save driver configuration after successful call
set PHI configuration property
appends property to PHI configuration and reloads module
http
PATCH /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "default_status": 1 }
curl
curl -i -X PATCH http://localhost:8812/r/phi/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"default_status": 1, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/phi/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"default_status": 1, "save": true}'
httpie
echo '{
"default_status": 1,
"save": true
}' | http PATCH http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/phi/test1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'default_status': 1,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
test PHI
Get PHI test result (as-is). All PHIs respond to self command, help command returns all available test commands.
http
POST /r/phi/test1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "self", "method": "test" }
curl
curl -i -X POST http://localhost:8812/r/phi/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "self", "method": "test"}'
wget
wget -S -O- http://localhost:8812/r/phi/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "self", "method": "test"}'
httpie
echo '{
"c": "self",
"method": "test"
}' | http POST http://localhost:8812/r/phi/test1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/phi/test1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'self',
'method': 'test',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"output": "OK"
}
Parameters:
- API Key API key with master permissions
unload PHI
Unloads PHI. PHI should not be used by any driver (except default, but the driver should not be in use by any item).
If driver <phi_id.default> (which’s loaded automatically with PHI) is present, it will be unloaded as well.
http
DELETE /r/phi/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/phi/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/phi/test2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/phi/test2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/phi/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
upload PHI module
Allows to upload new PHI module to xc/drivers/phi folder.
http
PUT /r/phi-module/gpio_button HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "<MODULE_CONTENT>" }
curl
curl -i -X PUT http://localhost:8812/r/phi-module/gpio_button -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "<MODULE_CONTENT>"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/phi-module/gpio_button --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"c": "<MODULE_CONTENT>"}'
httpie
echo '{
"c": "<MODULE_CONTENT>"
}' | http PUT http://localhost:8812/r/phi-module/gpio_button Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/phi-module/gpio_button', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': '<MODULE_CONTENT>',
})
response
HTTP/1.1 201 Created
Content-Type: application/json
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "GPIO buttons",
"equipment": [
"GPIO buttons"
],
"features": [
"events"
],
"help": " Handling pressed events from GPIO buttons.\n\nPHI doesn't provide any control/monitoring functions, each button can be\nconfigured as unit (via basic LPI) or sensor (via sensor) and contain its port\nin update_driver_config, update_interval should be set to 0.\n",
"license": "Apache License 2.0",
"lpi_default": "sensor",
"mod": "gpio_button",
"mods_required": [
"gpiozero"
],
"oid": null,
"required": [],
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
- c module content
Optionally:
- force overwrite PHI module file if exists
LPI and drivers
assign driver to item
Sets the specified driver to item, automatically updating item props:
- action_driver_config,**update_driver_config** to the specified configuration * action_exec, update_exec to do all operations via driver function calls (sets both to |<driver_id>)
To unassign driver, set driver ID to empty/null.
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "port=5", "method": "assign_driver", "d": "test2.my" }
curl
curl -i -X POST http://localhost:8812/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "port=5", "d": "test2.my", "method": "assign_driver"}'
wget
wget -S -O- http://localhost:8812/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "port=5", "d": "test2.my", "method": "assign_driver"}'
httpie
echo '{
"c": "port=5",
"d": "test2.my",
"method": "assign_driver"
}' | http POST http://localhost:8812/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'port=5',
'd': 'test2.my',
'method': 'assign_driver',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key masterkey
- d driver ID (if none - all above item props are set to null)
- c configuration (e.g. port number)
Optionally:
- save save item configuration after successful call
get LPI module info
http
GET /r/lpi-module/multistep HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/lpi-module/multistep -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/lpi-module/multistep --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/lpi-module/multistep X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/lpi-module/multistep', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"connections": {
"dport": "destination",
"port": "power"
},
"description": "Multistep LPI (opener)",
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration. Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"mod": "multistep",
"oid": null,
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
get LPI usage help
http
GET /r/lpi-module/multistep?help=cfg HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8812/r/lpi-module/multistep?help=cfg' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8812/r/lpi-module/multistep?help=cfg' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8812/r/lpi-module/multistep?help=cfg' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/lpi-module/multistep?help=cfg', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"help": "allow action even if current status is error",
"name": "bose",
"required": false,
"type": "bool"
}
]
Parameters:
- API Key API key with master permissions
get list of available LPI modules
http
GET /r/lpi-module HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/lpi-module -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/lpi-module --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/lpi-module X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/lpi-module', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"connections": {
"port": "primary"
},
"description": "Basic LPI for simple devices",
"features": [
"status",
"status_mp",
"mu_status",
"mu_status_mp",
"port_get",
"aao_get",
"action",
"action_mp",
"port_set",
"aao_set",
"events"
],
"help": "\nBasic LPI for simple unit status control (on/off) and monitoring. Support\nstatus 0 and 1. Unit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port' i.e. to\n'socket' for a more fancy unit configuration. Each port may be specified as a\nsingle value or contain an array of values, in this case multiple ports are\nused simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state.\n",
"id": null,
"license": "Apache License 2.0",
"logic": "basic status on/off",
"lpi_id": null,
"mod": "basic",
"oid": null,
"phi_id": null,
"version": "1.0.0"
}
]
Parameters:
- API Key API key with master permissions
get loaded driver information
http
GET /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/driver/test2.my -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/driver/test2.my --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/driver/test2.my X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/driver/test2.my', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {},
"connections": {
"dport": "destination",
"port": "power"
},
"description": "Multistep LPI (opener)",
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration. Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
"id": "test2.my",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"lpi_id": "my",
"mod": "multistep",
"oid": "driver:uc/mws1-v1/test2.my",
"phi": {
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 0
},
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"id": "test2",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test2",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
},
"phi_id": "test2",
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
list loaded drivers
http
GET /r/driver HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/driver -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/driver --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/driver X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/driver', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"id": "test.bose",
"lpi_id": "bose",
"mod": "multistep",
"phi_id": "test"
},
{
"features": [
"status",
"status_mp",
"mu_status",
"mu_status_mp",
"port_get",
"aao_get",
"action",
"action_mp",
"port_set",
"aao_set",
"events"
],
"id": "test.default",
"lpi_id": "default",
"mod": "basic",
"phi_id": "test"
}
]
Parameters:
- API Key API key with master permissions
- full get exntended information
load a driver
Loads a driver, combining previously loaded PHI and chosen LPI module.
http
PUT /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "multistep" }
curl
curl -i -X PUT http://localhost:8812/r/driver/test2.my -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "multistep"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/driver/test2.my --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"m": "multistep"}'
httpie
echo '{
"m": "multistep"
}' | http PUT http://localhost:8812/r/driver/test2.my Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/driver/test2.my', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'm': 'multistep',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {},
"connections": {
"dport": "destination",
"port": "power"
},
"description": "Multistep LPI (opener)",
"features": [
"action",
"action_mp",
"port_set",
"aao_set"
],
"help": "\nSolves typical logic task: turning the motor direction and run the motor for\nthe specified number of seconds, to control i.e. window opening, door opening,\nmanipulators of the robots.\n\nThe duration of the motor work is specified in 'steps' unit driver\nconfiguration param, each step corresponds to the next status.\n\nWarmup is used to let the motor additional number of seconds for the starting\nstates between first and last.\n\nTuning is used to make sure the motor drivers the target to starting and\nfinishing position (i.e. completely opens/closes the door).\n\nts and te. Sometimes it's pretty hard to calculate the proper position for the\nmiddle states. In this case LPI will ask motor to go all the way to the start\nstate (if target status <= ts) and then back to the target, or all the way to\nthe end and to the target (if target status >= te).\n\nUnit driver config fields should have property 'port' with a\nport label/number for PHI. 'io_label' prop allows to rename 'port', 'dport'\ni.e. to 'socket', 'dsocket' for a more fancy unit configuration. Each port and\ndport may be specified as a single value or contain an array of values, in this\ncase multiple ports are used simultaneously.\n\nYou may set i: before the port label/number, i.e. i:2, to return/use inverted\nport state. This works both for power and direction ports.\n",
"id": "test2.my",
"license": "Apache License 2.0",
"logic": "multistep with delays",
"lpi_id": "my",
"mod": "multistep",
"oid": "driver:uc/mws1-v1/test2.my",
"phi": {
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"default_status": 0
},
"description": "Emulates 16-port relay",
"equipment": [
"virtual"
],
"features": [
"port_get",
"port_set",
"aao_set",
"aao_get"
],
"help": "\nSimple 16-port virtual relay, may be used for the various tests/debugging.\n",
"id": "test2",
"license": "Apache License 2.0",
"lpi_default": "basic",
"mod": "vrtrelay",
"mods_required": [],
"oid": "phi:uc/mws1-v1/test2",
"required": [
"port_get",
"port_set"
],
"version": "1.0.1"
},
"phi_id": "test2",
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
- m LPI module
Optionally:
- c Driver (LPI) configuration, optional
- save save configuration after successful call
set driver (LPI) configuration property
appends property to LPI configuration and reloads module
http
PATCH /r/driver/test1.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "bose": 1 }
curl
curl -i -X PATCH http://localhost:8812/r/driver/test1.my -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"bose": 1, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/driver/test1.my --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"bose": 1, "save": true}'
httpie
echo '{
"bose": 1,
"save": true
}' | http PATCH http://localhost:8812/r/driver/test1.my Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/driver/test1.my', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'bose': 1,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save driver configuration after successful call
unload driver
Unloads driver. Driver should not be used by any item.
http
DELETE /r/driver/test2.my HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/driver/test2.my -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/driver/test2.my --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/driver/test2.my X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/driver/test2.my', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Devices
delete device items
Works in an opposite way to deploy_device - deploy device items from template function, destroying all items specified in the template.
http
POST /r/device-tpl/device1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "c": "PORT=2,ID=5", "method": "undeploy", "c": "PORT=3,ID=7" }
curl
curl -i -X POST http://localhost:8812/r/device-tpl/device1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "PORT=3,ID=7", "method": "undeploy"}'
wget
wget -S -O- http://localhost:8812/r/device-tpl/device1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "PORT=3,ID=7", "method": "undeploy"}'
httpie
echo '{
"c": "PORT=3,ID=7",
"method": "undeploy"
}' | http POST http://localhost:8812/r/device-tpl/device1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/device-tpl/device1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'PORT=3,ID=7',
'method': 'undeploy',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
Returns:
The function ignores missing items, so no errors are returned unless device configuration file is invalid.
deploy device items from template
Deploys the device from the specified template.
http
POST /r/device-tpl/device1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "deploy", "c": "PORT=3,ID=7", "save": true }
curl
curl -i -X POST http://localhost:8812/r/device-tpl/device1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "PORT=3,ID=7", "method": "deploy", "save": true}'
wget
wget -S -O- http://localhost:8812/r/device-tpl/device1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "PORT=3,ID=7", "method": "deploy", "save": true}'
httpie
echo '{
"c": "PORT=3,ID=7",
"method": "deploy",
"save": true
}' | http POST http://localhost:8812/r/device-tpl/device1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/device-tpl/device1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'PORT=3,ID=7',
'method': 'deploy',
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
list device templates
List available device templates from runtime/tpl
http
GET /r/device-tpl HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/device-tpl -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/device-tpl --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/device-tpl X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/device-tpl', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"name": "asic",
"type": "JSON"
},
{
"name": "device1",
"type": "YAML"
},
{
"name": "weatherapp",
"type": "JSON"
}
]
Parameters:
- API Key API key with masterkey permissions
update device items
Works similarly to deploy_device - deploy device items from template function but doesn’t create new items, updating the item configuration of the existing ones.
http
POST /r/device-tpl/device1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "update", "c": "PORT=3,ID=7", "save": true }
curl
curl -i -X POST http://localhost:8812/r/device-tpl/device1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "PORT=3,ID=7", "method": "update", "save": true}'
wget
wget -S -O- http://localhost:8812/r/device-tpl/device1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"c": "PORT=3,ID=7", "method": "update", "save": true}'
httpie
echo '{
"c": "PORT=3,ID=7",
"method": "update",
"save": true
}' | http POST http://localhost:8812/r/device-tpl/device1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/device-tpl/device1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'PORT=3,ID=7',
'method': 'update',
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with allow=device permissions
- t device template (runtime/tpl/<TEMPLATE>.yml|yaml|json, without extension)
Optionally:
- c device config (var=value, comma separated or dict)
- save save items configuration on disk immediately after operation
CVARs
get the value of user-defined variable
Note
Even if different EVA controllers are working on the same server, they have different sets of variables To set the variables for each subsystem, use SYS API on the respective address/port.
http
GET /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/cvar/test -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/cvar/test --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/cvar/test X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/cvar/test', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- API Key API key with master permissions
Optionally:
Returns:
Dict containing variable and its value. If no varible name was specified, all cvars are returned.
set the value of user-defined variable
http
PUT /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "some_value" }
curl
curl -i -X PUT http://localhost:8812/r/cvar/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "some_value"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/cvar/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": "some_value"}'
httpie
echo '{
"v": "some_value"
}' | http PUT http://localhost:8812/r/cvar/test Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/cvar/test', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': 'some_value',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- API Key API key with master permissions
Optionally:
- v variable value (if not specified, variable is deleted)
Locking functions
acquire lock
Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:
- centralized for several systems (any EVA server can act as lock server)
- removed from outside
- automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock
used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.
Note
Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.
http
PUT /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": 1, "t": 15 }
curl
curl -i -X PUT http://localhost:8812/r/lock/mylock1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": 1, "t": 15}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/lock/mylock1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": 1, "t": 15}'
httpie
echo '{
"e": 1,
"t": 15
}' | http PUT http://localhost:8812/r/lock/mylock1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/lock/mylock1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': 1,
't': 15,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"type": "lock"
}
Parameters:
- API Key API key with allow=lock permissions
Optionally:
- t maximum time (seconds) to acquire lock
- e time after which lock is automatically released (if absent, lock may be released only via unlock function)
get lock status
http
GET /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/lock/mylock1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"locked": true,
"type": "lock"
}
Parameters:
- API Key API key with allow=lock permissions
release lock
Releases the previously acquired lock.
http
DELETE /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/lock/mylock1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with allow=lock permissions
Logging
put message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /r/log/warning HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "local file system is full" }
curl
curl -i -X POST http://localhost:8812/r/log/warning -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "local file system is full"}'
wget
wget -S -O- http://localhost:8812/r/log/warning --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"m": "local file system is full"}'
httpie
echo '{
"m": "local file system is full"
}' | http POST http://localhost:8812/r/log/warning Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/log/warning', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'm': 'local file system is full',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
- l log level
- m message text
put debug message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put info message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put warning message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put error message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put critical message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
get records from the controller log
Log records are stored in the controllers’ memory until restart or the time (keep_logmem) specified in controller configuration passes.
http
GET /r/log/warning?t=3600&n=3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8812/r/log/warning?t=3600&n=3' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8812/r/log/warning?t=3600&n=3' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8812/r/log/warning?t=3600&n=3' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/log/warning?t=3600&n=3', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"h": "mws1-v1",
"l": 30,
"mod": "sysapi",
"msg": "test warning message",
"p": "uc",
"t": 1552863481.1394246,
"th": "CP Server Thread-15"
},
{
"h": "mws1-v1",
"l": 40,
"mod": "sysapi",
"msg": "test error message",
"p": "uc",
"t": 1552863481.1516943,
"th": "CP Server Thread-16"
},
{
"h": "mws1-v1",
"l": 50,
"mod": "sysapi",
"msg": "test critical message",
"p": "uc",
"t": 1552863481.1631815,
"th": "CP Server Thread-17"
}
]
Parameters:
- API Key API key with sysfunc=yes permissions
Optionally:
- t get log records not older than t seconds
- n the maximum number of log records you want to obtain
rotate log file
Equal to kill -HUP <controller_process_pid>.
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "log_rotate" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "log_rotate"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "log_rotate"}'
httpie
echo '{
"method": "log_rotate"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'log_rotate',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
API keys
create API key
API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.
Keys with master permission can not be created.
http
PUT /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true, "allow": "cmd" }
curl
curl -i -X PUT http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"allow": "cmd", "save": true, "sysfunc": true}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"allow": "cmd", "save": true, "sysfunc": true}'
httpie
echo '{
"allow": "cmd",
"save": true,
"sysfunc": true
}' | http PUT http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'allow': 'cmd',
'save': True,
'sysfunc': True,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [
"cmd"
],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey2",
"items": [],
"key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- API Key API key with master permissions
- save save configuration immediately
Returns:
JSON with serialized key object
delete API key
http
DELETE /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/key/testkey2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
list API key permissions
Lists API key permissons (including a key itself)
Note
API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.
http
GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/key/testkey2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [
"cmd"
],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey2",
"items": [],
"key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- API Key API key with master permissions
- save save configuration immediately
list API keys
http
GET /r/key HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/key -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/key --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/key X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/key', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"dynamic": false,
"key_id": "masterkey",
"master": true
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": true,
"groups": [
"#"
],
"items": [],
"key_id": "default",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "lm",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": true,
"lock": true
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "operator",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "sfa",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [
"item1"
],
"key_id": "t4",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [],
"items": [
"sensor:sensors/sensor1"
],
"key_id": "test",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": true,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey2",
"master": false,
"sysfunc": true
}
]
Parameters:
- API Key API key with master permissions
regenerate API key
http
POST /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "regenerate" }
curl
curl -i -X POST http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "regenerate"}'
wget
wget -S -O- http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "regenerate"}'
httpie
echo '{
"method": "regenerate"
}' | http POST http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'regenerate',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "3dbcd3d24c6dc878cebe369eb9fdb95ae99fee14e99cdfd911b83629688d2854"
}
Parameters:
- API Key API key with master permissions
Returns:
JSON dict with new key value in “key” field
set API key permissions
http
PATCH /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true }
curl
curl -i -X PATCH http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "sysfunc": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "sysfunc": true}'
httpie
echo '{
"save": true,
"sysfunc": true
}' | http PATCH http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'save': True,
'sysfunc': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- p property
- v value (if none, permission will be revoked)
- save save configuration immediately
User accounts
assign API key to user
http
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "masterkey" }
curl
curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "masterkey"}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "masterkey"}'
httpie
echo '{
"a": "masterkey"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'masterkey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- a API key to assign (key id, not a key itself)
create user account
Note
All changes to user accounts are instant, if the system works in read/only mode, set it to read/write before performing user management.
http
PUT /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "verysecretpassword", "a": "testkey" }
curl
curl -i -X PUT http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "testkey", "p": "verysecretpassword"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "testkey", "p": "verysecretpassword"}'
httpie
echo '{
"a": "testkey",
"p": "verysecretpassword"
}' | http PUT http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'testkey',
'p': 'verysecretpassword',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test2"
}
Parameters:
- API Key API key with master permissions
- p user password
- a API key to assign (key id, not a key itself)
delete user account
http
DELETE /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/user/test2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/user/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get user account info
http
GET /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/user/test2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/user/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test2"
}
Parameters:
- API Key API key with master permissions
list user accounts
http
GET /r/user HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/user -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/user --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/user X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/user', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"key": "test",
"user": "divisor"
},
{
"key": "testkey",
"user": "test"
},
{
"key": "testkey",
"user": "test2"
}
]
Parameters:
- API Key API key with master permissions
set user password
http
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "qwerty" }
curl
curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"p": "qwerty"}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"p": "qwerty"}'
httpie
echo '{
"p": "qwerty"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'p': 'qwerty',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- p new password
Notifier management
disable notifier
Note
The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.
http
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": false }
curl
curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false}'
httpie
echo '{
"enabled": false
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': False,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
enable notifier
Note
The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.
http
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": true }
curl
curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true}'
httpie
echo '{
"enabled": true
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get notifier configuration
http
GET /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/notifier/eva_1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/notifier/eva_1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/notifier/eva_1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/notifier/eva_1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
Parameters:
- API Key API key with master permissions
list notifiers
http
GET /r/notifier HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/notifier -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/notifier --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/notifier X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/notifier', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"db": "db1.db",
"enabled": true,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
}
],
"id": "db_1",
"keep": 86400,
"type": "db"
},
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
]
Parameters:
- API Key API key with master permissions
File management
put file to runtime folder
Puts a new file into runtime folder. If the file with such name exists, it will be overwritten. As all files in runtime are text, binary data can not be put.
http
PUT /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "/bin/sh\n\nexit 0", "e": true }
curl
curl -i -X PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true, "m": "/bin/sh\n\nexit 0"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true, "m": "/bin/sh\n\nexit 0"}'
httpie
echo '{
"e": true,
"m": "/bin/sh\n\nexit 0"
}' | http PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': True,
'm': '/bin/sh\n\nexit 0',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "xc/uc/test_action_script2",
"type": "runtime"
}
Parameters:
- API Key API key with master permissions
- m file content
set file exec permission
http
PATCH /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": true, "e": true }
curl
curl -i -X PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true}'
httpie
echo '{
"e": true
}' | http PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- e false for 0x644, true for 0x755 (executable)
delete file from runtime folder
http
DELETE /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get file contents from runtime folder
http
GET /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"data": "/bin/sh\n\nexit 0",
"e": true,
"file": "xc/uc/test_action_script2"
}
Parameters:
- API Key API key with master permissions
LM RESTful API
Logic Manager API is used to manage lvars, rules and other logic elements
This document describes API methods for RESTful calls. For direct and JSON RPC calls look LM API.
RESTful API basics
Majority EVA ICS API components and items support REST. Parameters for POST, PUT, PATCH and DELETE requests can be sent in both JSON and multipart/form-data. For JSON, Content-Type: application/json header must be specified.
Long API calls
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Requests
API key can be sent in HTTP X-Auth-Key header (preferred) or in request parameters (as k).
- GET request is used to get information about resource or list of resources of the specified type.
- POST request is used to perform special API calls and create resources in case when resource id is generated by server. In the last case, response always contains additional field Location which points to the resource created.
- PUT request is used to create new resources. If resource already exists, the server could refuse recreating it, responding with 409 Conflict HTTP error.
- PATCH request is used to modify resource parameters.
- DELETE request is used to delete resource.
For resource creation and modification, multiple parameters can be specified in a single request. For majority requests of such purpose, a special parameter “save” is used to tell server (if “save”: true) to save the resource configuration immediately after its modification.
For the group-related calls, put trailing slash at the end of the request URL:
/r/<resource_type>/<group>/
Responses
Success responses:
- 200 OK API call completed successfully
- 201 Created API call completed successfully, Response header Location contains either uri to the newly created object or resource is accessible by the effective request uri. For resources created with PUT, body contains either serialized resource object or resource type and id
- 202 Accepted The server accepted command and will process it later.
- 204 No Content API call completed successfully, no content to return
Error responses:
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found resource doesn’t exist
- 405 Method Not Allowed API function/method not found
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
Response body may contain additional information encoded in JSON. { “result”: “OK” } and { “result”: “ERROR” } in body are not returned.
Contents
- LM RESTful API
- RESTful API basics
- General functions
- LVar functions
- LVar management
- Decision matrix rules
- Logic control macros
- Logic cycles
- Macro extensions
- Remote controllers
- connect remote UC via HTTP
- disable connected controller
- disconnect controller
- enable connected controller
- get a list of items from connected UCs
- get connected controller information
- get controller connection parameters
- get controllers list
- reload controller
- set controller connection parameters
- test connection to remote controller
- Scheduled jobs
- CVARs
- Locking functions
- Logging
- API keys
- User accounts
- Notifier management
- File management
General functions
test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
GET /r/core HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/core -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/core --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/core X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/core', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"db_update": 1,
"debug": true,
"file_management": true,
"layout": "enterprise",
"polldelay": 0.01,
"product_build": 2019031405,
"product_code": "lm",
"product_name": "EVA Logic Manager",
"setup_mode": false,
"system": "ws1-v1",
"time": 1553193499.7972682,
"uptime": 658,
"version": "3.2.0"
}
Parameters:
- API Key any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
save database and runtime configuration
All modified items, their status, and configuration will be written to the disk. If exec_before_save command is defined in the controller’s configuration file, it’s called before saving and exec_after_save after (e.g. to switch the partition to write mode and back to read-only).
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'
httpie
echo '{
"method": "save"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'save',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
execute a remote system command
Executes a command script on the server where the controller is installed.
http
POST /r/cmd/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "0 2 3", "w": 5, "t": 10 }
curl
curl -i -X POST http://localhost:8812/r/cmd/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "0 2 3", "t": 10, "w": 5}'
wget
wget -S -O- http://localhost:8812/r/cmd/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "0 2 3", "t": 10, "w": 5}'
httpie
echo '{
"a": "0 2 3",
"t": 10,
"w": 5
}' | http POST http://localhost:8812/r/cmd/test Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/cmd/test', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': '0 2 3',
't': 10,
'w': 5,
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"args": [
"0",
"2",
"3"
],
"cmd": "test",
"err": "some text to stderr\n",
"exitcode": 0,
"out": "test script start\nparam 1: 0 ( > 0 will generate \"failed\" status)\nparam 2: 2\nparam 3: 3\ndelay 3 sec\nscript finish\n",
"status": "completed",
"time": {
"completed": 1552863480.7081513,
"created": 1552863480.6993306,
"running": 1552863480.7001197
},
"timeout": 10.0
}
Parameters:
- API Key API key with allow=cmd permissions
Optionally:
- a string of command arguments, separated by spaces (passed to the script)
- w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "shutdown" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "shutdown"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "shutdown"}'
httpie
echo '{
"method": "shutdown"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'shutdown',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
switch debugging mode
Enables and disables debugging mode while the controller is running. After the controller is restarted, this parameter is lost and controller switches back to the mode specified in the configuration file.
http
PATCH /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "debug": true }
curl
curl -i -X PATCH http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"debug": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"debug": true}'
httpie
echo '{
"debug": true
}' | http PATCH http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'debug': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- debug true for enabling debug mode, false for disabling
log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /r/token HTTP/1.1
Host: localhost:8817
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8817/r/token -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8817/r/token --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8817/r/token Content-Type:application/json
python-requests
requests.post('http://localhost:8817/r/token', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- API Key valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
log out and purge authentication token
Purges authentication token
http
DELETE /r/token HTTP/1.1
Host: localhost:8812
X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
curl
curl -i -X DELETE http://localhost:8812/r/token -H 'X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/token --header='X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'
httpie
http DELETE http://localhost:8812/r/token X-Auth-Key:token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
python-requests
requests.delete('http://localhost:8812/r/token', headers={
'X-Auth-Key': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid token
LVar functions
clear lvar state
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.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "s": "clear" }
curl
curl -i -X POST http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "clear"}'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "clear"}'
httpie
echo '{
"s": "clear"
}' | http POST http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 'clear',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
decrement lvar value
Decrement value of a logic variable. Initial value should be number
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "!decrement" }
curl
curl -i -X POST http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "!decrement"}'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"v": "!decrement"}'
httpie
echo '{
"v": "!decrement"
}' | http POST http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': '!decrement',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
GET /r/lvar/@groups HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lvar/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lvar/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lvar/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lvar/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"nogroup",
"tests",
"timers"
]
Parameters:
- API Key valid API key
get item state history
State history of one item or several items of the specified type can be obtained using state_history command.
http
GET /r/lvar/lvar:tests/lvar1@history HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lvar/lvar:tests/lvar1@history -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lvar/lvar:tests/lvar1@history --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lvar/lvar:tests/lvar1@history X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lvar/lvar:tests/lvar1@history', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"status": [
1,
1,
1
],
"t": [
1553193500.1192024,
1553193500.199146,
1553193500.2409995
],
"value": [
1.0,
null,
null
]
}
Parameters:
- API Key valid API key
- a history notifier id (default: db_1)
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
- g output format (“list”, “dict” or “chart”, default is “list”)
- c options for chart (dict or comma separated)
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
- type: chart type (line or bar, default is line)
- tf: chart time format
- out: output format (svg, png, default is svg),
- style: chart style (without “Style” suffix, e.g. Dark)
- other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
get lvar state
State of lvar or all lvars can be obtained using state command.
http
GET /r/lvar HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lvar -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lvar --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lvar X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lvar', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"expires": 0,
"full_id": "nogroup/flag1",
"group": "nogroup",
"id": "flag1",
"oid": "lvar:nogroup/flag1",
"set_time": 1528751049.3848495,
"status": 1,
"type": "lvar",
"value": "1"
},
{
"expires": 5.0,
"full_id": "nogroup/timer1",
"group": "nogroup",
"id": "timer1",
"oid": "lvar:nogroup/timer1",
"set_time": 1552049990.9313273,
"status": -1,
"type": "lvar",
"value": "null"
},
{
"expires": 15.0,
"full_id": "tests/lvar1",
"group": "tests",
"id": "lvar1",
"oid": "lvar:tests/lvar1",
"set_time": 1553193500.1979027,
"status": 1,
"type": "lvar",
"value": "null"
},
{
"expires": 30.0,
"full_id": "tests/lvar2",
"group": "tests",
"id": "lvar2",
"oid": "lvar:tests/lvar2",
"set_time": 1553193499.8252523,
"status": 1,
"type": "lvar",
"value": "null"
},
{
"expires": 100.0,
"full_id": "timers/timer1",
"group": "timers",
"id": "timer1",
"oid": "lvar:timers/timer1",
"set_time": 1552062897.9593153,
"status": -1,
"type": "lvar",
"value": "null"
}
]
Parameters:
- API Key valid API key
Optionally:
increment lvar value
Increment value of a logic variable. Initial value should be number
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "!increment" }
curl
curl -i -X POST http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "!increment"}'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"v": "!increment"}'
httpie
echo '{
"v": "!increment"
}' | http POST http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': '!increment',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
reset lvar state
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.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "s": "reset" }
curl
curl -i -X POST http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "reset"}'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "reset"}'
httpie
echo '{
"s": "reset"
}' | http POST http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 'reset',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
set lvar state
Set status and value of a logic variable.
http
POST /r/lvar/lvar:tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "s": 1, "v": 29.445 }
curl
curl -i -X POST http://localhost:8817/r/lvar/lvar:tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": 1, "v": 29.445}'
wget
wget -S -O- http://localhost:8817/r/lvar/lvar:tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": 1, "v": 29.445}'
httpie
echo '{
"s": 1,
"v": 29.445
}' | http POST http://localhost:8817/r/lvar/lvar:tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/lvar:tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 1,
'v': 29.445,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Optionally:
- s lvar status
- v lvar value
toggle lvar state
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.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "s": "toggle" }
curl
curl -i -X POST http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "toggle"}'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "toggle"}'
httpie
echo '{
"s": "toggle"
}' | http POST http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 'toggle',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
LVar management
list lvars
Parameters:
- API Key API key with master permissions
Optionally:
Returns:
the list of all lvars available
create lvar
Create new lvar
http
PUT /r/lvar/tests/lvar2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "expires": 30 }
curl
curl -i -X PUT http://localhost:8817/r/lvar/tests/lvar2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"expires": 30, "save": true}'
wget
wget -S -O- --method=PUT http://localhost:8817/r/lvar/tests/lvar2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"expires": 30, "save": true}'
httpie
echo '{
"expires": 30,
"save": true
}' | http PUT http://localhost:8817/r/lvar/tests/lvar2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8817/r/lvar/tests/lvar2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'expires': 30,
'save': True,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"config_changed": false,
"description": "",
"expires": 30.0,
"full_id": "tests/lvar2",
"group": "tests",
"id": "lvar2",
"oid": "lvar:tests/lvar2",
"set_time": 1553193499.8252523,
"status": 1,
"type": "lvar",
"value": "null"
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save lvar configuration immediately
delete lvar
http
DELETE /r/lvar/tests/lvar2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/lvar/tests/lvar2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/lvar/tests/lvar2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/lvar/tests/lvar2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/lvar/tests/lvar2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get lvar configuration
http
GET /r/lvar/tests/lvar2@config HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lvar/tests/lvar2@config -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar2@config --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lvar/tests/lvar2@config X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lvar/tests/lvar2@config', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"expires": 30.0,
"full_id": "tests/lvar2",
"group": "tests",
"id": "lvar2",
"oid": "lvar:tests/lvar2",
"set_time": 1553193499.8252523,
"type": "lvar"
}
Parameters:
- API Key API key with master permissions
Returns:
complete lvar configuration.
list lvar properties
Get all editable parameters of the lvar confiugration.
http
GET /r/lvar/tests/lvar1@props HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lvar/tests/lvar1@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lvar/tests/lvar1@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lvar/tests/lvar1@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"expires": 0,
"mqtt_update": null,
"set_time": 1553193500.117168,
"update_delay": 0,
"update_exec": null,
"update_interval": 0,
"update_timeout": null
}
Parameters:
- API Key API key with master permissions
save lvar configuration
Saves lvar. configuration on disk (even if it hasn’t been changed)
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
curl
curl -i -X POST http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'
wget
wget -S -O- http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'
httpie
echo '{
"method": "save"
}' | http POST http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'save',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
set lvar property
Set configuration parameters of the lvar.
http
PATCH /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "expires": 15 }
curl
curl -i -X PATCH http://localhost:8817/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"expires": 15}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"expires": 15}'
httpie
echo '{
"expires": 15
}' | http PATCH http://localhost:8817/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'expires': 15,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
Decision matrix rules
create new rule
Creates new decision rule. Rule id (UUID) is generated automatically unless specified.
http
POST /r/dmatrix_rule HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X POST http://localhost:8817/r/dmatrix_rule -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/dmatrix_rule --header='X-Auth-Key: mykey'
httpie
http POST http://localhost:8817/r/dmatrix_rule X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/dmatrix_rule', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/dmatrix_rule/cc7de0ba-04a1-4161-ad73-588861b6e1ef
Pragma: no-cache
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "cc7de0ba-04a1-4161-ad73-588861b6e1ef",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/cc7de0ba-04a1-4161-ad73-588861b6e1ef",
"priority": 100,
"type": "dmatrix_rule"
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save rule configuration immediately
delete rule
Deletes decision rule.
http
DELETE /r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get rule information
http
GET /r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "4c6e8c99-56fe-490c-8442-4936ba777498",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/4c6e8c99-56fe-490c-8442-4936ba777498",
"priority": 100,
"type": "dmatrix_rule"
}
Parameters:
- API Key valid API key
get rules list
Get the list of all available decision rules.
http
GET /r/dmatrix_rule HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/dmatrix_rule -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/dmatrix_rule --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/dmatrix_rule X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/dmatrix_rule', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "4c6e8c99-56fe-490c-8442-4936ba777498",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/4c6e8c99-56fe-490c-8442-4936ba777498",
"priority": 100,
"type": "dmatrix_rule"
},
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "9b317323-00e5-4e11-8573-33cdcada1d12",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/9b317323-00e5-4e11-8573-33cdcada1d12",
"priority": 100,
"type": "dmatrix_rule"
},
{
"break_after_exec": false,
"chillout_ends_in": 0,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"id": "cc7de0ba-04a1-4161-ad73-588861b6e1ef",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "dmatrix_rule:dm_rules/cc7de0ba-04a1-4161-ad73-588861b6e1ef",
"priority": 100,
"type": "dmatrix_rule"
}
]
Parameters:
- API Key valid API key
list rule properties
Get all editable parameters of the decision rule.
http
GET /r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498@props HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"break_after_exec": false,
"chillout_time": 0,
"condition": "",
"description": "",
"enabled": false,
"for_initial": "skip",
"for_item_group": null,
"for_item_id": null,
"for_item_type": null,
"for_oid": "#:#/#/status",
"for_prop": "status",
"in_range_max": null,
"in_range_max_eq": false,
"in_range_min": null,
"in_range_min_eq": false,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"priority": 100
}
Parameters:
- API Key valid API key
set rule parameters
Set configuration parameters of the decision rule.
Note
Master key is required for batch set.
http
PATCH /r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "for_initial": "any", "enabled": true }
curl
curl -i -X PATCH http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true, "for_initial": "any", "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true, "for_initial": "any", "save": true}'
httpie
echo '{
"enabled": true,
"for_initial": "any",
"save": true
}' | http PATCH http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/dmatrix_rule/4c6e8c99-56fe-490c-8442-4936ba777498', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
'for_initial': 'any',
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Optionally:
- save save configuration after successful call
Logic control macros
create new macro
Creates new macro. Macro code should be put in xc/lm manually.
http
PUT /r/lmacro/tests/test_macro2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X PUT http://localhost:8817/r/lmacro/tests/test_macro2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=PUT http://localhost:8817/r/lmacro/tests/test_macro2 --header='X-Auth-Key: mykey'
httpie
http PUT http://localhost:8817/r/lmacro/tests/test_macro2 X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8817/r/lmacro/tests/test_macro2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"full_id": "tests/test_macro2",
"group": "tests",
"id": "test_macro2",
"oid": "lmacro:tests/test_macro2",
"type": "lmacro"
}
Parameters:
- API Key API key with master permissions
Optionally:
delete macro
Deletes macro.
http
DELETE /r/lmacro/tests/test_macro2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/lmacro/tests/test_macro2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/lmacro/tests/test_macro2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/lmacro/tests/test_macro2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/lmacro/tests/test_macro2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
execute macro
Execute a macro with the specified arguments.
http
POST /r/lmacro/tests/test_macro HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "run" }
curl
curl -i -X POST http://localhost:8817/r/lmacro/tests/test_macro -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "run"}'
wget
wget -S -O- http://localhost:8817/r/lmacro/tests/test_macro --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "run"}'
httpie
echo '{
"method": "run"
}' | http POST http://localhost:8817/r/lmacro/tests/test_macro Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lmacro/tests/test_macro', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'run',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/68574286-35f8-4b52-b8e0-f51c6dafddf5
Pragma: no-cache
{
"args": [],
"err": "",
"exitcode": null,
"finished": false,
"finished_in": null,
"item_group": "tests",
"item_id": "test_macro",
"item_oid": "lmacro:tests/test_macro",
"item_type": "lmacro",
"kwargs": {},
"out": "",
"priority": 100,
"status": "running",
"time": {
"created": 1559868831.9411464,
"pending": 1559868831.9414475,
"queued": 1559868831.9422777,
"running": 1559868831.9430113
},
"uuid": "68574286-35f8-4b52-b8e0-f51c6dafddf5"
}
Parameters:
- API Key valid API key
Optionally:
- a macro arguments, array or space separated
- kw macro keyword arguments, name=value, comma separated or dict
- w wait for the completion for the specified number of seconds
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
get macro configuration properties
http
GET /r/lmacro/tests/test_macro@props HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lmacro/tests/test_macro@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lmacro/tests/test_macro@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lmacro/tests/test_macro@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lmacro/tests/test_macro@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"action_exec": null,
"description": "",
"pass_errors": false,
"send_critical": false
}
Parameters:
- API Key API key with master permissions
get macro groups list
Get the list of macros. Useful e.g. for custom interfaces.
http
GET /r/lmacro/@groups HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lmacro/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lmacro/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lmacro/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lmacro/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"tests"
]
Parameters:
- API Key valid API key
get macro information
http
GET /r/lmacro/tests/test_macro HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lmacro/tests/test_macro -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lmacro/tests/test_macro --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lmacro/tests/test_macro X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lmacro/tests/test_macro', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"action_enabled": true,
"description": "",
"full_id": "tests/test_macro",
"group": "tests",
"id": "test_macro",
"oid": "lmacro:tests/test_macro",
"type": "lmacro"
}
Parameters:
- API Key valid API key
get macro list
Get the list of all available macros.
http
GET /r/lmacro HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lmacro -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lmacro --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lmacro X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lmacro', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"action_enabled": true,
"description": "",
"full_id": "tests/test1",
"group": "tests",
"id": "test1",
"oid": "lmacro:tests/test1",
"type": "lmacro"
},
{
"action_enabled": true,
"description": "",
"full_id": "tests/test2",
"group": "tests",
"id": "test2",
"oid": "lmacro:tests/test2",
"type": "lmacro"
},
{
"action_enabled": true,
"description": "",
"full_id": "tests/test_macro",
"group": "tests",
"id": "test_macro",
"oid": "lmacro:tests/test_macro",
"type": "lmacro"
},
{
"action_enabled": true,
"description": "",
"full_id": "tests/test_macro2",
"group": "tests",
"id": "test_macro2",
"oid": "lmacro:tests/test_macro2",
"type": "lmacro"
}
]
Parameters:
- API Key valid API key
Optionally:
macro execution result
Get macro execution results either by action uuid or by macro id.
http
GET /r/action?i=tests%2Ftest_macro HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8817/r/action?i=tests%2Ftest_macro' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8817/r/action?i=tests%2Ftest_macro' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8817/r/action?i=tests%2Ftest_macro' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/action?i=tests%2Ftest_macro', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"args": [],
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0097811,
"item_group": "tests",
"item_id": "test_macro",
"item_oid": "lmacro:tests/test_macro",
"item_type": "lmacro",
"kwargs": {},
"out": "test passed",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559868831.1551707,
"created": 1559868831.1453896,
"pending": 1559868831.1458647,
"queued": 1559868831.1469553,
"running": 1559868831.1479862
},
"uuid": "7707c382-eefa-48d2-9b5e-92d114af4e85"
}
]
Parameters:
- API Key valid API key
Optionally:
- g filter by unit group
- s filter by action status: Q for queued, R for running, F for finished
Returns:
list or single serialized action object
set macro configuration property
Set configuration parameters of the macro.
http
PATCH /r/lmacro/tests/test_macro HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "pass_errors": true }
curl
curl -i -X PATCH http://localhost:8817/r/lmacro/tests/test_macro -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"pass_errors": true, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/lmacro/tests/test_macro --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"pass_errors": true, "save": true}'
httpie
echo '{
"pass_errors": true,
"save": true
}' | http PATCH http://localhost:8817/r/lmacro/tests/test_macro Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/lmacro/tests/test_macro', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'pass_errors': True,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
Logic cycles
create new cycle
Creates new cycle.
http
PUT /r/lcycle/tests/test_cycle2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X PUT http://localhost:8817/r/lcycle/tests/test_cycle2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=PUT http://localhost:8817/r/lcycle/tests/test_cycle2 --header='X-Auth-Key: mykey'
httpie
http PUT http://localhost:8817/r/lcycle/tests/test_cycle2 X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8817/r/lcycle/tests/test_cycle2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"full_id": "tests/test_cycle2",
"group": "tests",
"ict": 100,
"id": "test_cycle2",
"interval": 1,
"macro": null,
"oid": "lcycle:tests/test_cycle2",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "1.0000"
}
Parameters:
- API Key API key with master permissions
Optionally:
delete cycle
Deletes cycle. If cycle is running, it is stopped before deletion.
http
DELETE /r/lcycle/tests/test_cycle2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/lcycle/tests/test_cycle2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/lcycle/tests/test_cycle2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/lcycle/tests/test_cycle2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/lcycle/tests/test_cycle2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get cycle configuration properties
http
GET /r/lcycle/tests/test_cycle@props HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lcycle/tests/test_cycle@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lcycle/tests/test_cycle@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lcycle/tests/test_cycle@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lcycle/tests/test_cycle@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"autostart": false,
"description": "",
"ict": 20,
"interval": 1,
"macro": "tests/test_macro",
"on_error": null
}
Parameters:
- API Key API key with master permissions
get cycle groups list
Get the list of cycles. Useful e.g. for custom interfaces.
http
GET /r/lcycle/@groups HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lcycle/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lcycle/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lcycle/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lcycle/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"tests"
]
Parameters:
- API Key valid API key
get cycle information
http
GET /r/lcycle/tests/test_cycle HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lcycle/tests/test_cycle -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lcycle/tests/test_cycle --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lcycle/tests/test_cycle X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lcycle/tests/test_cycle', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"avg": 1,
"description": "",
"full_id": "tests/test_cycle",
"group": "tests",
"ict": 20,
"id": "test_cycle",
"interval": 1,
"iterations": 0,
"macro": "tests/test_macro",
"oid": "lcycle:tests/test_cycle",
"on_error": null,
"status": 1,
"type": "lcycle",
"value": "1.0000"
}
Parameters:
- API Key valid API key
Returns:
field “value” contains real average cycle interval
get cycle list
Get the list of all available cycles.
http
GET /r/lcycle HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/lcycle -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/lcycle --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/lcycle X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/lcycle', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"avg": 0.0105,
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"ict": 20,
"id": "cycle1",
"interval": 0.01,
"iterations": 275,
"macro": "tests/test",
"oid": "lcycle:tests/cycle1",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "275,0.0105,"
},
{
"avg": 0.5,
"description": "test 2Hz cycle",
"full_id": "tests/test1",
"group": "tests",
"ict": 100,
"id": "test1",
"interval": 0.5,
"iterations": 0,
"macro": "tests/test1",
"oid": "lcycle:tests/test1",
"on_error": null,
"status": 0,
"type": "lcycle",
"value": "0,0.5000,"
}
]
Parameters:
- API Key valid API key
Optionally:
reset cycle statistic
http
POST /r/lcycle/tests/test_cycle HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "reset" }
curl
curl -i -X POST http://localhost:8817/r/lcycle/tests/test_cycle -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "reset"}'
wget
wget -S -O- http://localhost:8817/r/lcycle/tests/test_cycle --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "reset"}'
httpie
echo '{
"method": "reset"
}' | http POST http://localhost:8817/r/lcycle/tests/test_cycle Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lcycle/tests/test_cycle', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'reset',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
set cycle property
Set configuration parameters of the cycle.
http
PATCH /r/lcycle/tests/test_cycle HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "ict": 20, "macro": "tests/test_macro" }
curl
curl -i -X PATCH http://localhost:8817/r/lcycle/tests/test_cycle -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"ict": 20, "macro": "tests/test_macro", "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/lcycle/tests/test_cycle --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"ict": 20, "macro": "tests/test_macro", "save": true}'
httpie
echo '{
"ict": 20,
"macro": "tests/test_macro",
"save": true
}' | http PATCH http://localhost:8817/r/lcycle/tests/test_cycle Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/lcycle/tests/test_cycle', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'ict': 20,
'macro': 'tests/test_macro',
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
start cycle
http
POST /r/lcycle/tests/test_cycle HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "start" }
curl
curl -i -X POST http://localhost:8817/r/lcycle/tests/test_cycle -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "start"}'
wget
wget -S -O- http://localhost:8817/r/lcycle/tests/test_cycle --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "start"}'
httpie
echo '{
"method": "start"
}' | http POST http://localhost:8817/r/lcycle/tests/test_cycle Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lcycle/tests/test_cycle', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'start',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
stop cycle
http
POST /r/lcycle/tests/test_cycle HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "stop" }
curl
curl -i -X POST http://localhost:8817/r/lcycle/tests/test_cycle -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "stop"}'
wget
wget -S -O- http://localhost:8817/r/lcycle/tests/test_cycle --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "stop"}'
httpie
echo '{
"method": "stop"
}' | http POST http://localhost:8817/r/lcycle/tests/test_cycle Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/lcycle/tests/test_cycle', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'stop',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Optionally:
- wait wait until cycle is stopped
Macro extensions
get extension module info
http
GET /r/ext-module/audio HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/ext-module/audio -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/ext-module/audio --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/ext-module/audio X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/ext-module/audio', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
get extension usage help
http
GET /r/ext-module/audio?help=functions HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8817/r/ext-module/audio?help=functions' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8817/r/ext-module/audio?help=functions' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8817/r/ext-module/audio?help=functions' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/ext-module/audio?help=functions', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"play(soundfile, gain=0, wait=True)": "Play sound file"
}
Parameters:
- API Key API key with master permissions
get list of available extension modules
http
GET /r/ext-module HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/ext-module -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/ext-module --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/ext-module X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/ext-module', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"id": null,
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
},
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Push client for Roboger",
"help": "\nPush client for Roboger event pager (https://www.roboger.com,\nhttps://github.com/alttch/roboger). Refer to pyrpush module documentation for\nmore info: https://pypi.org/project/pyrpush/\n",
"id": null,
"license": "Apache License 2.0",
"mod": "rpush",
"mods_required": [
"pyrpush"
],
"version": "1.0.0"
},
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Run macro on remote LM PLC",
"help": "\nAllows to run macros on remote LM PLC\n",
"id": null,
"license": "Apache License 2.0",
"mod": "run_remote",
"mods_required": [],
"version": "1.0.0"
},
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"description": "Text-to-speech via ttsbroker",
"help": "\nText-to-speech engine via ttsbroker Python module. Refer to module\ndocumentation for more info: https://pypi.org/project/ttsbroker/\n",
"id": null,
"license": "Apache License 2.0",
"mod": "tts",
"mods_required": [
"ttsbroker"
],
"version": "1.0.0"
}
]
Parameters:
- API Key API key with master permissions
get list of available macro extensions
http
GET /r/ext HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/ext -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/ext --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/ext X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/ext', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"id": "a1",
"mod": "audio"
},
{
"id": "test_a",
"mod": "audio"
},
{
"id": "test_a2",
"mod": "audio"
}
]
Parameters:
- API Key API key with master permissions
Optionally:
get loaded extension information
http
GET /r/ext/test_a HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/ext/test_a -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/ext/test_a --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/ext/test_a X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/ext/test_a', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"sdir": "/opt/data/snd"
},
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"id": "test_a",
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
load extension module
Loads:doc:macro extension</lm/ext>.
http
PUT /r/ext/test_a2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "audio", "c": "sdir=/opt/data/snd", "save": true }
curl
curl -i -X PUT http://localhost:8817/r/ext/test_a2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"c": "sdir=/opt/data/snd", "m": "audio", "save": true}'
wget
wget -S -O- --method=PUT http://localhost:8817/r/ext/test_a2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"c": "sdir=/opt/data/snd", "m": "audio", "save": true}'
httpie
echo '{
"c": "sdir=/opt/data/snd",
"m": "audio",
"save": true
}' | http PUT http://localhost:8817/r/ext/test_a2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8817/r/ext/test_a2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'c': 'sdir=/opt/data/snd',
'm': 'audio',
'save': True,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"api": 1,
"author": "Altertech Group, https://www.altertech.com/",
"cfg": {
"sdir": "/opt/data/snd"
},
"description": "Play audio file",
"help": "\nPlays audio file inside the specified directory. The file path should be\nrelative to the directory root, witout a starting slash.\n",
"id": "test_a2",
"license": "Apache License 2.0",
"mod": "audio",
"mods_required": [
"soundfile",
"sounddevice"
],
"version": "1.0.0"
}
Parameters:
- API Key API key with master permissions
- m extension module
Optionally:
- c extension configuration
- save save extension configuration after successful call
set extension configuration property
appends property to extension configuration and reloads module
http
PATCH /r/ext/test_a HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "d": 2, "save": true }
curl
curl -i -X PATCH http://localhost:8817/r/ext/test_a -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"d": 2, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/ext/test_a --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"d": 2, "save": true}'
httpie
echo '{
"d": 2,
"save": true
}' | http PATCH http://localhost:8817/r/ext/test_a Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/ext/test_a', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'd': 2,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
unload macro extension
http
DELETE /r/ext/test_a2 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/ext/test_a2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/ext/test_a2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/ext/test_a2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/ext/test_a2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Remote controllers
connect remote UC via HTTP
Connects remote UC controller to the local.
http
POST /r/controller/uc HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "u": "localhost", "a": "secretkey", "save": true }
curl
curl -i -X POST http://localhost:8817/r/controller/uc -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "secretkey", "save": true, "u": "localhost"}'
wget
wget -S -O- http://localhost:8817/r/controller/uc --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "secretkey", "save": true, "u": "localhost"}'
httpie
echo '{
"a": "secretkey",
"save": true,
"u": "localhost"
}' | http POST http://localhost:8817/r/controller/uc Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/controller/uc', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'secretkey',
'save': True,
'u': 'localhost',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/controller/uc/ws1-v1
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- API Key API key with master permissions
- u UC API uri (proto://host:port, port not required if default)
- a remote controller API key ($key to use local key)
Optionally:
- m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)
- s verify remote SSL certificate or pass invalid
- t timeout (seconds) for the remote controller API calls
- save save connected controller configuration on the disk immediately after creation
disable connected controller
http
PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "enabled": false }
curl
curl -i -X PATCH http://localhost:8817/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false, "save": true}'
httpie
echo '{
"enabled": false,
"save": true
}' | http PATCH http://localhost:8817/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': False,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
disconnect controller
http
DELETE /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/controller/uc/ws1-v1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/controller/uc/ws1-v1 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/controller/uc/ws1-v1 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
enable connected controller
http
PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "enabled": true }
curl
curl -i -X PATCH http://localhost:8817/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true, "save": true}'
httpie
echo '{
"enabled": true,
"save": true
}' | http PATCH http://localhost:8817/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
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.
http
GET /r/controller/uc/ws1-v1@items HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/controller/uc/ws1-v1@items -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/controller/uc/ws1-v1@items --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/controller/uc/ws1-v1@items X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/controller/uc/ws1-v1@items', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "env/temp_test",
"group": "env",
"id": "temp_test",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"oid": "sensor:env/temp_test",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"action_enabled": true,
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "nogroup/test2",
"group": "nogroup",
"id": "test2",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"nstatus": -1,
"nvalue": "null",
"oid": "unit:nogroup/test2",
"status": -1,
"status_labels": [
{
"label": "OFF",
"status": 0
},
{
"label": "ON",
"status": 1
}
],
"type": "unit",
"value": "null"
}
]
Parameters:
- API Key API key with master permissions
Optionally:
- g filter by item group
- p filter by item type
get connected controller information
http
GET /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/controller/uc/ws1-v1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/controller/uc/ws1-v1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/controller/uc/ws1-v1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- API Key API key with master permissions
get controller connection parameters
http
GET /r/controller/uc/ws1-v1@props HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/controller/uc/ws1-v1@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/controller/uc/ws1-v1@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/controller/uc/ws1-v1@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/controller/uc/ws1-v1@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"key": "secretkey",
"mqtt_update": null,
"reload_interval": 300,
"retries": 2,
"ssl_verify": true,
"static": true,
"timeout": 5.0,
"uri": "http://localhost:8812"
}
Parameters:
- API Key API key with master permissions
get controllers list
Get the list of all connected UC controllers.
http
GET /r/controller HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/controller -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/controller --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/controller X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/controller', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[]
Parameters:
- API Key API key with master permissions
reload controller
Reloads items from connected UC
http
POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "reload" }
curl
curl -i -X POST http://localhost:8817/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "reload"}'
wget
wget -S -O- http://localhost:8817/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "reload"}'
httpie
echo '{
"method": "reload"
}' | http POST http://localhost:8817/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'reload',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
set controller connection parameters
http
PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "reload_interval": 60 }
curl
curl -i -X PATCH http://localhost:8817/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"reload_interval": 60, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"reload_interval": 60, "save": true}'
httpie
echo '{
"reload_interval": 60,
"save": true
}' | http PATCH http://localhost:8817/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'reload_interval': 60,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
test connection to remote controller
http
POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "test" }
curl
curl -i -X POST http://localhost:8817/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'
wget
wget -S -O- http://localhost:8817/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'
httpie
echo '{
"method": "test"
}' | http POST http://localhost:8817/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'test',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Scheduled jobs
create new job
Creates new scheduled job. Job id (UUID) is generated automatically unless specified.
http
POST /r/job HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X POST http://localhost:8817/r/job -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/job --header='X-Auth-Key: mykey'
httpie
http POST http://localhost:8817/r/job X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8817/r/job', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/job/32ec1063-26cc-4f73-ba40-73ffc2e1787b
Pragma: no-cache
{
"description": "",
"enabled": false,
"every": "",
"id": "32ec1063-26cc-4f73-ba40-73ffc2e1787b",
"last": null,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "job:jobs/32ec1063-26cc-4f73-ba40-73ffc2e1787b",
"type": "job"
}
Parameters:
- API Key API key with master permissions
Optionally:
- save save unit configuration immediately
delete job
Deletes scheduled job.
http
DELETE /r/job/9c6e8c99-56fe-490c-8442-4936ba777499 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get job information
http
GET /r/job/9c6e8c99-56fe-490c-8442-4936ba777499 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"every": "",
"id": "9c6e8c99-56fe-490c-8442-4936ba777499",
"last": null,
"macro": "tests/test1",
"macro_args": [
"test"
],
"macro_kwargs": {},
"oid": "job:jobs/9c6e8c99-56fe-490c-8442-4936ba777499",
"type": "job"
}
Parameters:
- API Key API key with master permissions
get jobs list
Get the list of all available scheduled jobs.
http
GET /r/job HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/job -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/job --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/job X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/job', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"description": "",
"enabled": false,
"every": "",
"id": "9d8a338f-cdc4-46ac-8610-ba3b1597c73e",
"last": null,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "job:jobs/9d8a338f-cdc4-46ac-8610-ba3b1597c73e",
"type": "job"
},
{
"description": "",
"enabled": false,
"every": "",
"id": "7545a768-ce67-44ad-9544-2a54ad6c7e83",
"last": null,
"macro": null,
"macro_args": [],
"macro_kwargs": {},
"oid": "job:jobs/7545a768-ce67-44ad-9544-2a54ad6c7e83",
"type": "job"
}
]
Parameters:
- API Key API key with master permissions
list job properties
Get all editable parameters of the scheduled job.
http
GET /r/job/9c6e8c99-56fe-490c-8442-4936ba777499@props HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
curl
curl -i http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"every": "",
"macro": "tests/test1",
"macro_args": [
"test"
],
"macro_kwargs": {}
}
Parameters:
- API Key API key with master permissions
set job parameters
Set configuration parameters of the scheduled job.
http
PATCH /r/job/9c6e8c99-56fe-490c-8442-4936ba777499 HTTP/1.1
Host: localhost:8817
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "macro": "tests/test1", "enabled": true }
curl
curl -i -X PATCH http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true, "macro": "tests/test1", "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true, "macro": "tests/test1", "save": true}'
httpie
echo '{
"enabled": true,
"macro": "tests/test1",
"save": true
}' | http PATCH http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8817/r/job/9c6e8c99-56fe-490c-8442-4936ba777499', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
'macro': 'tests/test1',
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
CVARs
get the value of user-defined variable
Note
Even if different EVA controllers are working on the same server, they have different sets of variables To set the variables for each subsystem, use SYS API on the respective address/port.
http
GET /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/cvar/test -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/cvar/test --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/cvar/test X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/cvar/test', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- API Key API key with master permissions
Optionally:
Returns:
Dict containing variable and its value. If no varible name was specified, all cvars are returned.
set the value of user-defined variable
http
PUT /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "some_value" }
curl
curl -i -X PUT http://localhost:8812/r/cvar/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "some_value"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/cvar/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": "some_value"}'
httpie
echo '{
"v": "some_value"
}' | http PUT http://localhost:8812/r/cvar/test Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/cvar/test', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': 'some_value',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- API Key API key with master permissions
Optionally:
- v variable value (if not specified, variable is deleted)
Locking functions
acquire lock
Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:
- centralized for several systems (any EVA server can act as lock server)
- removed from outside
- automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock
used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.
Note
Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.
http
PUT /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": 1, "t": 15 }
curl
curl -i -X PUT http://localhost:8812/r/lock/mylock1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": 1, "t": 15}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/lock/mylock1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": 1, "t": 15}'
httpie
echo '{
"e": 1,
"t": 15
}' | http PUT http://localhost:8812/r/lock/mylock1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/lock/mylock1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': 1,
't': 15,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"type": "lock"
}
Parameters:
- API Key API key with allow=lock permissions
Optionally:
- t maximum time (seconds) to acquire lock
- e time after which lock is automatically released (if absent, lock may be released only via unlock function)
get lock status
http
GET /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/lock/mylock1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"locked": true,
"type": "lock"
}
Parameters:
- API Key API key with allow=lock permissions
release lock
Releases the previously acquired lock.
http
DELETE /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/lock/mylock1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with allow=lock permissions
Logging
put message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /r/log/warning HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "local file system is full" }
curl
curl -i -X POST http://localhost:8812/r/log/warning -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "local file system is full"}'
wget
wget -S -O- http://localhost:8812/r/log/warning --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"m": "local file system is full"}'
httpie
echo '{
"m": "local file system is full"
}' | http POST http://localhost:8812/r/log/warning Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/log/warning', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'm': 'local file system is full',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
- l log level
- m message text
put debug message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put info message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put warning message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put error message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put critical message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
get records from the controller log
Log records are stored in the controllers’ memory until restart or the time (keep_logmem) specified in controller configuration passes.
http
GET /r/log/warning?t=3600&n=3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8812/r/log/warning?t=3600&n=3' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8812/r/log/warning?t=3600&n=3' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8812/r/log/warning?t=3600&n=3' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/log/warning?t=3600&n=3', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"h": "mws1-v1",
"l": 30,
"mod": "sysapi",
"msg": "test warning message",
"p": "uc",
"t": 1552863481.1394246,
"th": "CP Server Thread-15"
},
{
"h": "mws1-v1",
"l": 40,
"mod": "sysapi",
"msg": "test error message",
"p": "uc",
"t": 1552863481.1516943,
"th": "CP Server Thread-16"
},
{
"h": "mws1-v1",
"l": 50,
"mod": "sysapi",
"msg": "test critical message",
"p": "uc",
"t": 1552863481.1631815,
"th": "CP Server Thread-17"
}
]
Parameters:
- API Key API key with sysfunc=yes permissions
Optionally:
- t get log records not older than t seconds
- n the maximum number of log records you want to obtain
rotate log file
Equal to kill -HUP <controller_process_pid>.
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "log_rotate" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "log_rotate"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "log_rotate"}'
httpie
echo '{
"method": "log_rotate"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'log_rotate',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
API keys
create API key
API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.
Keys with master permission can not be created.
http
PUT /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true, "allow": "cmd" }
curl
curl -i -X PUT http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"allow": "cmd", "save": true, "sysfunc": true}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"allow": "cmd", "save": true, "sysfunc": true}'
httpie
echo '{
"allow": "cmd",
"save": true,
"sysfunc": true
}' | http PUT http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'allow': 'cmd',
'save': True,
'sysfunc': True,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [
"cmd"
],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey2",
"items": [],
"key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- API Key API key with master permissions
- save save configuration immediately
Returns:
JSON with serialized key object
delete API key
http
DELETE /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/key/testkey2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
list API key permissions
Lists API key permissons (including a key itself)
Note
API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.
http
GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/key/testkey2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [
"cmd"
],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey2",
"items": [],
"key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- API Key API key with master permissions
- save save configuration immediately
list API keys
http
GET /r/key HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/key -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/key --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/key X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/key', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"dynamic": false,
"key_id": "masterkey",
"master": true
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": true,
"groups": [
"#"
],
"items": [],
"key_id": "default",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "lm",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": true,
"lock": true
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "operator",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "sfa",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [
"item1"
],
"key_id": "t4",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [],
"items": [
"sensor:sensors/sensor1"
],
"key_id": "test",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": true,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey2",
"master": false,
"sysfunc": true
}
]
Parameters:
- API Key API key with master permissions
regenerate API key
http
POST /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "regenerate" }
curl
curl -i -X POST http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "regenerate"}'
wget
wget -S -O- http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "regenerate"}'
httpie
echo '{
"method": "regenerate"
}' | http POST http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'regenerate',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "3dbcd3d24c6dc878cebe369eb9fdb95ae99fee14e99cdfd911b83629688d2854"
}
Parameters:
- API Key API key with master permissions
Returns:
JSON dict with new key value in “key” field
set API key permissions
http
PATCH /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true }
curl
curl -i -X PATCH http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "sysfunc": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "sysfunc": true}'
httpie
echo '{
"save": true,
"sysfunc": true
}' | http PATCH http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'save': True,
'sysfunc': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- p property
- v value (if none, permission will be revoked)
- save save configuration immediately
User accounts
assign API key to user
http
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "masterkey" }
curl
curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "masterkey"}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "masterkey"}'
httpie
echo '{
"a": "masterkey"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'masterkey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- a API key to assign (key id, not a key itself)
create user account
Note
All changes to user accounts are instant, if the system works in read/only mode, set it to read/write before performing user management.
http
PUT /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "verysecretpassword", "a": "testkey" }
curl
curl -i -X PUT http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "testkey", "p": "verysecretpassword"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "testkey", "p": "verysecretpassword"}'
httpie
echo '{
"a": "testkey",
"p": "verysecretpassword"
}' | http PUT http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'testkey',
'p': 'verysecretpassword',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test2"
}
Parameters:
- API Key API key with master permissions
- p user password
- a API key to assign (key id, not a key itself)
delete user account
http
DELETE /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/user/test2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/user/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get user account info
http
GET /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/user/test2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/user/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test2"
}
Parameters:
- API Key API key with master permissions
list user accounts
http
GET /r/user HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/user -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/user --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/user X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/user', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"key": "test",
"user": "divisor"
},
{
"key": "testkey",
"user": "test"
},
{
"key": "testkey",
"user": "test2"
}
]
Parameters:
- API Key API key with master permissions
set user password
http
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "qwerty" }
curl
curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"p": "qwerty"}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"p": "qwerty"}'
httpie
echo '{
"p": "qwerty"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'p': 'qwerty',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- p new password
Notifier management
disable notifier
Note
The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.
http
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": false }
curl
curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false}'
httpie
echo '{
"enabled": false
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': False,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
enable notifier
Note
The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.
http
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": true }
curl
curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true}'
httpie
echo '{
"enabled": true
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get notifier configuration
http
GET /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/notifier/eva_1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/notifier/eva_1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/notifier/eva_1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/notifier/eva_1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
Parameters:
- API Key API key with master permissions
list notifiers
http
GET /r/notifier HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/notifier -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/notifier --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/notifier X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/notifier', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"db": "db1.db",
"enabled": true,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
}
],
"id": "db_1",
"keep": 86400,
"type": "db"
},
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
]
Parameters:
- API Key API key with master permissions
File management
put file to runtime folder
Puts a new file into runtime folder. If the file with such name exists, it will be overwritten. As all files in runtime are text, binary data can not be put.
http
PUT /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "/bin/sh\n\nexit 0", "e": true }
curl
curl -i -X PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true, "m": "/bin/sh\n\nexit 0"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true, "m": "/bin/sh\n\nexit 0"}'
httpie
echo '{
"e": true,
"m": "/bin/sh\n\nexit 0"
}' | http PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': True,
'm': '/bin/sh\n\nexit 0',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "xc/uc/test_action_script2",
"type": "runtime"
}
Parameters:
- API Key API key with master permissions
- m file content
set file exec permission
http
PATCH /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": true, "e": true }
curl
curl -i -X PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true}'
httpie
echo '{
"e": true
}' | http PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- e false for 0x644, true for 0x755 (executable)
delete file from runtime folder
http
DELETE /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get file contents from runtime folder
http
GET /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"data": "/bin/sh\n\nexit 0",
"e": true,
"file": "xc/uc/test_action_script2"
}
Parameters:
- API Key API key with master permissions
SFA RESTful API
SCADA Final Aggregator API is used to manage EVA ICS cloud and aggregated resources.
This document describes API methods for RESTful calls. For direct and JSON RPC calls look SFA API.
RESTful API basics
Majority EVA ICS API components and items support REST. Parameters for POST, PUT, PATCH and DELETE requests can be sent in both JSON and multipart/form-data. For JSON, Content-Type: application/json header must be specified.
Long API calls
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Requests
API key can be sent in HTTP X-Auth-Key header (preferred) or in request parameters (as k).
- GET request is used to get information about resource or list of resources of the specified type.
- POST request is used to perform special API calls and create resources in case when resource id is generated by server. In the last case, response always contains additional field Location which points to the resource created.
- PUT request is used to create new resources. If resource already exists, the server could refuse recreating it, responding with 409 Conflict HTTP error.
- PATCH request is used to modify resource parameters.
- DELETE request is used to delete resource.
For resource creation and modification, multiple parameters can be specified in a single request. For majority requests of such purpose, a special parameter “save” is used to tell server (if “save”: true) to save the resource configuration immediately after its modification.
For the group-related calls, put trailing slash at the end of the request URL:
/r/<resource_type>/<group>/
Responses
Success responses:
- 200 OK API call completed successfully
- 201 Created API call completed successfully, Response header Location contains either uri to the newly created object or resource is accessible by the effective request uri. For resources created with PUT, body contains either serialized resource object or resource type and id
- 202 Accepted The server accepted command and will process it later.
- 204 No Content API call completed successfully, no content to return
Error responses:
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found resource doesn’t exist
- 405 Method Not Allowed API function/method not found
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
Response body may contain additional information encoded in JSON. { “result”: “OK” } and { “result”: “ERROR” } in body are not returned.
Contents
- SFA RESTful API
- RESTful API basics
- General functions
- Item functions
- clean action queue of unit
- create unit control action
- disable unit actions
- enable unit actions
- get action status or macro run result
- get item group list
- get item state
- get item state history
- kill unit actions
- terminate action execution
- toggle unit status
- clear lvar state
- clear lvar state
- reset lvar state
- set lvar state
- LVar functions
- Logic control macros
- Logic cycles
- Remote controllers
- connect remote controller via HTTP
- disable connected controller
- disconnect controller
- enable connected controller
- get a list of items from connected controllers
- get connected controller information
- get controller connection parameters
- get controllers list
- reload controller
- set controller connection parameters
- test connection to remote controller
- test management API connection to remote controller
- Connected clients
- CVARs
- Locking functions
- Logging
- API keys
- User accounts
- Notifier management
- File management
General functions
test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
GET /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/core -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/core --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/core X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/core', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"acl": {
"key_id": "masterkey",
"master": true
},
"cloud_manager": true,
"db_update": 1,
"debug": true,
"file_management": true,
"polldelay": 0.01,
"product_build": 2019032301,
"product_code": "sfa",
"product_name": "EVA SCADA Final Aggregator",
"setup_mode": false,
"system": "mws1-v1",
"time": 1553393178.4744968,
"uptime": 2,
"version": "3.2.0"
}
Parameters:
- API Key any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
save database and runtime configuration
All modified items, their status, and configuration will be written to the disk. If exec_before_save command is defined in the controller’s configuration file, it’s called before saving and exec_after_save after (e.g. to switch the partition to write mode and back to read-only).
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "save" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'
httpie
echo '{
"method": "save"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'save',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
execute a remote system command
Executes a command script on the server where the controller is installed.
http
POST /r/cmd/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "0 2 3", "w": 5, "t": 10 }
curl
curl -i -X POST http://localhost:8812/r/cmd/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "0 2 3", "t": 10, "w": 5}'
wget
wget -S -O- http://localhost:8812/r/cmd/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "0 2 3", "t": 10, "w": 5}'
httpie
echo '{
"a": "0 2 3",
"t": 10,
"w": 5
}' | http POST http://localhost:8812/r/cmd/test Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/cmd/test', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': '0 2 3',
't': 10,
'w': 5,
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"args": [
"0",
"2",
"3"
],
"cmd": "test",
"err": "some text to stderr\n",
"exitcode": 0,
"out": "test script start\nparam 1: 0 ( > 0 will generate \"failed\" status)\nparam 2: 2\nparam 3: 3\ndelay 3 sec\nscript finish\n",
"status": "completed",
"time": {
"completed": 1552863480.7081513,
"created": 1552863480.6993306,
"running": 1552863480.7001197
},
"timeout": 10.0
}
Parameters:
- API Key API key with allow=cmd permissions
Optionally:
- a string of command arguments, separated by spaces (passed to the script)
- w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "shutdown" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "shutdown"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "shutdown"}'
httpie
echo '{
"method": "shutdown"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'shutdown',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
switch debugging mode
Enables and disables debugging mode while the controller is running. After the controller is restarted, this parameter is lost and controller switches back to the mode specified in the configuration file.
http
PATCH /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "debug": true }
curl
curl -i -X PATCH http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"debug": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"debug": true}'
httpie
echo '{
"debug": true
}' | http PATCH http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'debug': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- debug true for enabling debug mode, false for disabling
log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /r/token HTTP/1.1
Host: localhost:8828
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8828/r/token -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8828/r/token --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8828/r/token Content-Type:application/json
python-requests
requests.post('http://localhost:8828/r/token', headers={
'Content-Type': 'application/json',
}, json={
'p': '123',
'u': 'admin',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- API Key valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
log out and purge authentication token
Purges authentication token
http
DELETE /r/token HTTP/1.1
Host: localhost:8812
X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
curl
curl -i -X DELETE http://localhost:8812/r/token -H 'X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/token --header='X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'
httpie
http DELETE http://localhost:8812/r/token X-Auth-Key:token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7
python-requests
requests.delete('http://localhost:8812/r/token', headers={
'X-Auth-Key': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid token
Item functions
clean action queue of unit
Cancels all queued actions, keeps the current action running.
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "q_clean" }
curl
curl -i -X POST http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "q_clean"}'
wget
wget -S -O- http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "q_clean"}'
httpie
echo '{
"method": "q_clean"
}' | http POST http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'q_clean',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
create unit control action
The call is considered successful when action is put into the action queue of selected unit.
http
POST /r/action HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "s": 1, "i": "unit:tests/unit3", "s": 1 }
curl
curl -i -X POST http://localhost:8828/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": 1}'
wget
wget -S -O- http://localhost:8828/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": 1}'
httpie
echo '{
"i": "unit:tests/unit3",
"s": 1
}' | http POST http://localhost:8828/r/action Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/action', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'i': 'unit:tests/unit3',
's': 1,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/751955a9-9eb6-451b-8069-706bd445a9f7
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0009174,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868835.769016,
"pending": 1559868835.769214,
"refused": 1559868835.7699335
},
"uuid": "751955a9-9eb6-451b-8069-706bd445a9f7"
}
Parameters:
- API Key valid API key
Optionally:
- s desired unit status
- v desired unit value
- w wait for the completion for the specified number of seconds
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
disable unit actions
Disables unit to run and queue new actions.
http
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "action_enabled": false }
curl
curl -i -X PATCH http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": false}'
wget
wget -S -O- --method=PATCH http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": false}'
httpie
echo '{
"action_enabled": false
}' | http PATCH http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8828/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'action_enabled': False,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
enable unit actions
Enables unit to run and queue new actions.
http
PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "action_enabled": true }
curl
curl -i -X PATCH http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": true}'
wget
wget -S -O- --method=PATCH http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": true}'
httpie
echo '{
"action_enabled": true
}' | http PATCH http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8828/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'action_enabled': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
get action status or macro run result
Checks the result of the action by its UUID or returns the actions for the specified unit or execution result of the specified macro.
http
GET /r/action?i=unit%3Atests%2Funit1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8828/r/action?i=unit%3Atests%2Funit1' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8828/r/action?i=unit%3Atests%2Funit1' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8828/r/action?i=unit%3Atests%2Funit1' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/action?i=unit%3Atests%2Funit1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0006144,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.0452583,
"pending": 1559868829.0455182,
"refused": 1559868829.0458727
},
"uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0010161,
"item_group": "tests",
"item_id": "unit1",
"item_oid": "unit:tests/unit1",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868829.087297,
"pending": 1559868829.0876813,
"refused": 1559868829.088313
},
"uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0005889,
"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": 1559868835.75104,
"pending": 1559868835.751197,
"refused": 1559868835.7516289
},
"uuid": "d2aab822-ec47-4370-8145-f8f455db4d27"
},
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.001091,
"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": 1559868835.7902575,
"pending": 1559868835.7906036,
"refused": 1559868835.7913485
},
"uuid": "8038de65-3833-4aa5-94c1-c0f0e86eb3fe"
}
]
Parameters:
- API Key valid API key
Optionally:
- g filter by unit group
- s filter by action status: Q for queued, R for running, F for finished
Returns:
list or single serialized action object
get item group list
Get the list of item groups. Useful e.g. for custom interfaces.
http
GET /r/unit/@groups HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/unit/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/unit/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/unit/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/unit/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"mb",
"room1",
"tests"
]
Parameters:
- API Key valid API key
get item state
State of the item or all items of the specified type can be obtained using state command.
http
GET /r/sensor HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/sensor -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/sensor --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/sensor X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/sensor', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "uc/mws1-v1",
"full_id": "env/temp_test",
"group": "env",
"id": "temp_test",
"oid": "sensor:env/temp_test",
"status": 1,
"type": "sensor",
"value": "191"
},
{
"controller_id": "uc/mws1-v1",
"full_id": "room1/lamps",
"group": "room1",
"id": "lamps",
"oid": "sensor:room1/lamps",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"controller_id": "uc/mws1-v1",
"full_id": "room2/h",
"group": "room2",
"id": "h",
"oid": "sensor:room2/h",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"controller_id": "uc/mws1-v1",
"full_id": "room2/lamps",
"group": "room2",
"id": "lamps",
"oid": "sensor:room2/lamps",
"status": 0,
"type": "sensor",
"value": "null"
}
]
Parameters:
- API Key valid API key
Optionally:
get item state history
State history of one item or several items of the specified type can be obtained using state_history command.
http
GET /r/sensor/env/temp_test@history HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/sensor/env/temp_test@history -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/sensor/env/temp_test@history --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/sensor/env/temp_test@history X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/sensor/env/temp_test@history', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"status": [
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1,
1
],
"t": [
1553390125.8643427,
1553390140.929797,
1553390334.862889,
1553390589.4016967,
1553390732.9677052,
1553391169.14625,
1553391188.7430675,
1553391215.390878,
1553391623.3912942,
1553391746.352703,
1553391851.0065582,
1553391951.145705,
1553391968.589165,
1553392069.766155,
1553392157.956836,
1553392366.729588,
1553392495.9142005,
1553392581.9080076,
1553393041.2446685,
1553393176.3235447
],
"value": [
19.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0,
191.0
]
}
Parameters:
- API Key valid API key
- a history notifier id (default: db_1)
Optionally:
- s start time (timestamp or ISO or e.g. 1D for -1 day)
- e end time (timestamp or ISO or e.g. 1D for -1 day)
- l records limit (doesn’t work with “w”)
- x state prop (“status” or “value”)
- t time format(“iso” or “raw” for unix timestamp, default is “raw”)
- w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
- g output format (“list”, “dict” or “chart”, default is “list”)
- c options for chart (dict or comma separated)
Returns:
history data in specified format or chart image.
For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.
Options for chart (all are optional):
- type: chart type (line or bar, default is line)
- tf: chart time format
- out: output format (svg, png, default is svg),
- style: chart style (without “Style” suffix, e.g. Dark)
- other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.
Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.
If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.
kill unit actions
Apart from canceling all queued commands, this function also terminates the current running action.
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "kill" }
curl
curl -i -X POST http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "kill"}'
wget
wget -S -O- http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "kill"}'
httpie
echo '{
"method": "kill"
}' | http POST http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'kill',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Returns:
If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)
terminate action execution
Terminates or cancel the action if it is still queued
http
POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "terminate" }
curl
curl -i -X POST http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "terminate"}'
wget
wget -S -O- http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "terminate"}'
httpie
echo '{
"method": "terminate"
}' | http POST http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/unit/tests/unit3', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'terminate',
})
response
HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Returns:
An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)
toggle unit status
Create unit control action to toggle its status (1->0, 0->1)
http
POST /r/action HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "i": "unit:tests/unit3", "s": "toggle" }
curl
curl -i -X POST http://localhost:8828/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": "toggle"}'
wget
wget -S -O- http://localhost:8828/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": "toggle"}'
httpie
echo '{
"i": "unit:tests/unit3",
"s": "toggle"
}' | http POST http://localhost:8828/r/action Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/action', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'i': 'unit:tests/unit3',
's': 'toggle',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/afaab4be-67b5-4906-a32d-1339bcbae5a3
Pragma: no-cache
{
"err": "",
"exitcode": null,
"finished": true,
"finished_in": 0.0006881,
"item_group": "tests",
"item_id": "unit3",
"item_oid": "unit:tests/unit3",
"item_type": "unit",
"nstatus": 1,
"nvalue": null,
"out": "",
"priority": 100,
"status": "refused",
"time": {
"created": 1559868835.8054502,
"pending": 1559868835.805737,
"refused": 1559868835.8061383
},
"uuid": "afaab4be-67b5-4906-a32d-1339bcbae5a3"
}
Parameters:
- API Key valid API key
Optionally:
- w wait for the completion for the specified number of seconds
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
Returns:
Serialized action object. If action is marked as dead, an error is returned (exception raised)
clear lvar state
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.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "s": "clear" }
curl
curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "clear"}'
wget
wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "clear"}'
httpie
echo '{
"s": "clear"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 'clear',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
clear lvar state
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.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "s": "toggle" }
curl
curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "toggle"}'
wget
wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "toggle"}'
httpie
echo '{
"s": "toggle"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 'toggle',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
reset lvar state
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.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "s": "reset" }
curl
curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "reset"}'
wget
wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "reset"}'
httpie
echo '{
"s": "reset"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 'reset',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
set lvar state
Set status and value of a logic variable.
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "s": 1, "v": 29 }
curl
curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": 1, "v": 29}'
wget
wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": 1, "v": 29}'
httpie
echo '{
"s": 1,
"v": 29
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
's': 1,
'v': 29,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Optionally:
- s lvar status
- v lvar value
LVar functions
decrement lvar value
Decrement value of a logic variable. Initial value should be number
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "!decrement" }
curl
curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "!decrement"}'
wget
wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"v": "!decrement"}'
httpie
echo '{
"v": "!decrement"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': '!decrement',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
increment lvar value
Increment value of a logic variable. Initial value should be number
http
POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "!increment" }
curl
curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "!increment"}'
wget
wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"v": "!increment"}'
httpie
echo '{
"v": "!increment"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': '!increment',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key valid API key
Logic control macros
execute macro
Execute a macro with the specified arguments.
http
POST /r/lmacro/tests/test1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "run" }
curl
curl -i -X POST http://localhost:8828/r/lmacro/tests/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "run"}'
wget
wget -S -O- http://localhost:8828/r/lmacro/tests/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "run"}'
httpie
echo '{
"method": "run"
}' | http POST http://localhost:8828/r/lmacro/tests/test1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/lmacro/tests/test1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'run',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/6ea7dc1f-2934-45da-8209-d29d7d1d9259
Pragma: no-cache
{
"args": [],
"err": "",
"exitcode": 0,
"finished": true,
"finished_in": 0.0030398,
"item_group": "tests",
"item_id": "test1",
"item_oid": "lmacro:tests/test1",
"item_type": "lmacro",
"kwargs": {},
"out": "",
"priority": 100,
"status": "completed",
"time": {
"completed": 1559868836.280482,
"created": 1559868836.2774422,
"pending": 1559868836.2777095,
"queued": 1559868836.2782526,
"running": 1559868836.2789273
},
"uuid": "6ea7dc1f-2934-45da-8209-d29d7d1d9259"
}
Parameters:
- API Key valid API key
Optionally:
- a macro arguments, array or space separated
- kw macro keyword arguments, name=value, comma separated or dict
- w wait for the completion for the specified number of seconds
- p queue priority (default is 100, lower is better)
- q global queue timeout, if expires, action is marked as “dead”
get macro groups list
Get the list of macros. Useful e.g. for custom interfaces.
http
GET /r/lmacro/@groups HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/lmacro/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/lmacro/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/lmacro/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/lmacro/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"nogroup",
"tests"
]
Parameters:
- API Key valid API key
get macro list
Get the list of all available macros.
http
GET /r/lmacro HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/lmacro -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/lmacro --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/lmacro X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/lmacro', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "nogroup/lr",
"group": "nogroup",
"id": "lr",
"oid": "lmacro:nogroup/lr",
"type": "lmacro"
},
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "test macro",
"full_id": "tests/test",
"group": "tests",
"id": "test",
"oid": "lmacro:tests/test",
"type": "lmacro"
},
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/test1",
"group": "tests",
"id": "test1",
"oid": "lmacro:tests/test1",
"type": "lmacro"
},
{
"action_enabled": true,
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/test2",
"group": "tests",
"id": "test2",
"oid": "lmacro:tests/test2",
"type": "lmacro"
}
]
Parameters:
- API Key valid API key
Optionally:
- i filter by controller
Logic cycles
get cycle groups list
Get the list of cycles. Useful e.g. for custom interfaces.
http
GET /r/lcycle/@groups HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/lcycle/@groups -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/lcycle/@groups --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/lcycle/@groups X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/lcycle/@groups', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
"tests"
]
Parameters:
- API Key valid API key
get cycle information
http
GET /r/lcycle/tests/cycle1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/lcycle/tests/cycle1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/lcycle/tests/cycle1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/lcycle/tests/cycle1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/lcycle/tests/cycle1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"id": "cycle1",
"interval": 0.01,
"oid": "lcycle:tests/cycle1",
"type": "lcycle"
}
Parameters:
- API Key valid API key
Returns:
field “value” contains real average cycle interval
get cycle list
Get the list of all available cycles.
http
GET /r/lcycle HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/lcycle -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/lcycle --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/lcycle X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/lcycle', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "lm/mws1-v1",
"description": "",
"full_id": "tests/cycle1",
"group": "tests",
"id": "cycle1",
"interval": 0.01,
"oid": "lcycle:tests/cycle1",
"status": 0,
"type": "lcycle",
"value": "0,0.0100,"
},
{
"controller_id": "lm/mws1-v1",
"description": "test 2Hz cycle",
"full_id": "tests/test1",
"group": "tests",
"id": "test1",
"interval": 0.5,
"oid": "lcycle:tests/test1",
"status": 0,
"type": "lcycle",
"value": "0,0.5000,"
}
]
Parameters:
- API Key valid API key
Optionally:
- i filter by controller
Remote controllers
connect remote controller via HTTP
Connects remote controller to the local.
http
POST /r/controller/uc HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "u": "localhost", "a": "secretkey", "save": true }
curl
curl -i -X POST http://localhost:8828/r/controller/uc -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "secretkey", "save": true, "u": "localhost"}'
wget
wget -S -O- http://localhost:8828/r/controller/uc --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "secretkey", "save": true, "u": "localhost"}'
httpie
echo '{
"a": "secretkey",
"save": true,
"u": "localhost"
}' | http POST http://localhost:8828/r/controller/uc Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/controller/uc', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'secretkey',
'save': True,
'u': 'localhost',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/controller/uc/ws1-v1
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- API Key API key with master permissions
- u Controller API uri (proto://host:port, port not required if default)
- a remote controller API key ($key to use local key)
Optionally:
- m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)
- s verify remote SSL certificate or pass invalid
- t timeout (seconds) for the remote controller API calls
- g controller type (“uc” or “lm”), autodetected if none
- save save connected controller configuration on the disk immediately after creation
disable connected controller
http
PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "enabled": false }
curl
curl -i -X PATCH http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false, "save": true}'
httpie
echo '{
"enabled": false,
"save": true
}' | http PATCH http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': False,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
disconnect controller
http
DELETE /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8828/r/controller/uc/ws1-v1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8828/r/controller/uc/ws1-v1 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8828/r/controller/uc/ws1-v1 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
enable connected controller
http
PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "enabled": true }
curl
curl -i -X PATCH http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true, "save": true}'
httpie
echo '{
"enabled": true,
"save": true
}' | http PATCH http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
get a list of items from connected controllers
Get a list of the items loaded from the connected controllers. Useful to debug the controller connections.
http
GET /r/controller/uc/ws1-v1@items HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/controller/uc/ws1-v1@items -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1@items --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/controller/uc/ws1-v1@items X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/controller/uc/ws1-v1@items', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "env/temp_test",
"group": "env",
"id": "temp_test",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"oid": "sensor:env/temp_test",
"status": 0,
"type": "sensor",
"value": "null"
},
{
"action_enabled": true,
"controller_id": "uc/ws1-v1",
"description": "",
"full_id": "nogroup/test2",
"group": "nogroup",
"id": "test2",
"loc_x": null,
"loc_y": null,
"loc_z": null,
"location": "",
"nstatus": -1,
"nvalue": "null",
"oid": "unit:nogroup/test2",
"status": -1,
"status_labels": [
{
"label": "OFF",
"status": 0
},
{
"label": "ON",
"status": 1
}
],
"type": "unit",
"value": "null"
}
]
Parameters:
- API Key API key with master permissions
Optionally:
- g filter by item group
- p filter by item type
get connected controller information
http
GET /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/controller/uc/ws1-v1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/controller/uc/ws1-v1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"build": "2019031405",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/ws1-v1",
"group": "uc",
"id": "ws1-v1",
"managed": false,
"mqtt_update": null,
"oid": "remote_uc:uc/ws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
Parameters:
- API Key API key with master permissions
get controller connection parameters
http
GET /r/controller/uc/ws1-v1@props HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/controller/uc/ws1-v1@props -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1@props --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/controller/uc/ws1-v1@props X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/controller/uc/ws1-v1@props', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"description": "",
"enabled": true,
"key": "secretkey",
"mqtt_update": null,
"reload_interval": 300,
"retries": 2,
"ssl_verify": true,
"static": true,
"timeout": 5.0,
"uri": "http://localhost:8812"
}
Parameters:
- API Key API key with master permissions
get controllers list
Get the list of all connected controllers.
http
GET /r/controller HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i http://localhost:8828/r/controller -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8828/r/controller --header='X-Auth-Key: mykey'
httpie
http http://localhost:8828/r/controller X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/controller', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"build": "2019032301",
"connected": true,
"description": "",
"enabled": true,
"full_id": "lm/mws1-v1",
"group": "lm",
"id": "mws1-v1",
"managed": false,
"mqtt_update": "eva_1",
"oid": "remote_lm:lm/mws1-v1",
"proto": "http",
"static": true,
"type": "remote_lm",
"version": "3.2.0"
},
{
"build": "2019032301",
"connected": true,
"description": "",
"enabled": true,
"full_id": "uc/mws1-v1",
"group": "uc",
"id": "mws1-v1",
"managed": false,
"mqtt_update": "eva_1",
"oid": "remote_uc:uc/mws1-v1",
"proto": "http",
"static": true,
"type": "remote_uc",
"version": "3.2.0"
}
]
Parameters:
- API Key API key with master permissions
reload controller
Reloads items from connected controller. If controller ID “ALL” is specified, all connected controllers are reloaded.
http
POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "reload" }
curl
curl -i -X POST http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "reload"}'
wget
wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "reload"}'
httpie
echo '{
"method": "reload"
}' | http POST http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'reload',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
set controller connection parameters
http
PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "reload_interval": 60 }
curl
curl -i -X PATCH http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"reload_interval": 60, "save": true}'
wget
wget -S -O- --method=PATCH http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"reload_interval": 60, "save": true}'
httpie
echo '{
"reload_interval": 60,
"save": true
}' | http PATCH http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'reload_interval': 60,
'save': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Optionally:
- save save configuration after successful call
test connection to remote controller
http
POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "test" }
curl
curl -i -X POST http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'
wget
wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'
httpie
echo '{
"method": "test"
}' | http POST http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'test',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
test management API connection to remote controller
http
POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "matest" }
curl
curl -i -X POST http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "matest"}'
wget
wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "matest"}'
httpie
echo '{
"method": "matest"
}' | http POST http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/controller/uc/ws1-v1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'matest',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
Connected clients
ask connected clients to reload
Sends reload event to all connected clients asking them to reload the interface.
All the connected clients receive the event with subject=”reload” and data=”asap”. If the clients use EVA JS Framework, they can catch server.reload event.
http
POST /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "reload_clients" }
curl
curl -i -X POST http://localhost:8828/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "reload_clients"}'
wget
wget -S -O- http://localhost:8828/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "reload_clients"}'
httpie
echo '{
"method": "reload_clients"
}' | http POST http://localhost:8828/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'reload_clients',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
notify connected clients about server restart
Sends a server restart event to all connected clients asking them to prepare for server restart.
All the connected clients receive the event with subject=”server” and data=”restart”. If the clients use EVA JS Framework, they can catch server.restart event.
Server restart notification is sent automatically to all connected clients when the server is restarting. This API function allows to send server restart notification without actual server restart, which may be useful e.g. for testing, handling frontend restart etc.
http
POST /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "notify_restart" }
curl
curl -i -X POST http://localhost:8828/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "notify_restart"}'
wget
wget -S -O- http://localhost:8828/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "notify_restart"}'
httpie
echo '{
"method": "notify_restart"
}' | http POST http://localhost:8828/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'notify_restart',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
CVARs
get the value of user-defined variable
Note
Even if different EVA controllers are working on the same server, they have different sets of variables To set the variables for each subsystem, use SYS API on the respective address/port.
http
GET /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/cvar/test -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/cvar/test --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/cvar/test X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/cvar/test', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- API Key API key with master permissions
Optionally:
Returns:
Dict containing variable and its value. If no varible name was specified, all cvars are returned.
set the value of user-defined variable
http
PUT /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "v": "some_value" }
curl
curl -i -X PUT http://localhost:8812/r/cvar/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "some_value"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/cvar/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": "some_value"}'
httpie
echo '{
"v": "some_value"
}' | http PUT http://localhost:8812/r/cvar/test Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/cvar/test', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'v': 'some_value',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"test": "some_value"
}
Parameters:
- API Key API key with master permissions
Optionally:
- v variable value (if not specified, variable is deleted)
Locking functions
acquire lock
Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:
- centralized for several systems (any EVA server can act as lock server)
- removed from outside
- automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock
used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.
Note
Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.
http
PUT /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": 1, "t": 15 }
curl
curl -i -X PUT http://localhost:8812/r/lock/mylock1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": 1, "t": 15}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/lock/mylock1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": 1, "t": 15}'
httpie
echo '{
"e": 1,
"t": 15
}' | http PUT http://localhost:8812/r/lock/mylock1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/lock/mylock1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': 1,
't': 15,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"type": "lock"
}
Parameters:
- API Key API key with allow=lock permissions
Optionally:
- t maximum time (seconds) to acquire lock
- e time after which lock is automatically released (if absent, lock may be released only via unlock function)
get lock status
http
GET /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/lock/mylock1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "mylock1",
"locked": true,
"type": "lock"
}
Parameters:
- API Key API key with allow=lock permissions
release lock
Releases the previously acquired lock.
http
DELETE /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/lock/mylock1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with allow=lock permissions
Logging
put message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /r/log/warning HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "local file system is full" }
curl
curl -i -X POST http://localhost:8812/r/log/warning -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "local file system is full"}'
wget
wget -S -O- http://localhost:8812/r/log/warning --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"m": "local file system is full"}'
httpie
echo '{
"m": "local file system is full"
}' | http POST http://localhost:8812/r/log/warning Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/log/warning', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'm': 'local file system is full',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
- l log level
- m message text
put debug message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put info message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put warning message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put error message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
put critical message to log file
An external application can put a message in the logs on behalf of the controller.
Parameters:
- API Key API key with sysfunc=yes permissions
- m message text
get records from the controller log
Log records are stored in the controllers’ memory until restart or the time (keep_logmem) specified in controller configuration passes.
http
GET /r/log/warning?t=3600&n=3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i 'http://localhost:8812/r/log/warning?t=3600&n=3' -H 'X-Auth-Key: mykey'
wget
wget -S -O- 'http://localhost:8812/r/log/warning?t=3600&n=3' --header='X-Auth-Key: mykey'
httpie
http 'http://localhost:8812/r/log/warning?t=3600&n=3' X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/log/warning?t=3600&n=3', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"h": "mws1-v1",
"l": 30,
"mod": "sysapi",
"msg": "test warning message",
"p": "uc",
"t": 1552863481.1394246,
"th": "CP Server Thread-15"
},
{
"h": "mws1-v1",
"l": 40,
"mod": "sysapi",
"msg": "test error message",
"p": "uc",
"t": 1552863481.1516943,
"th": "CP Server Thread-16"
},
{
"h": "mws1-v1",
"l": 50,
"mod": "sysapi",
"msg": "test critical message",
"p": "uc",
"t": 1552863481.1631815,
"th": "CP Server Thread-17"
}
]
Parameters:
- API Key API key with sysfunc=yes permissions
Optionally:
- t get log records not older than t seconds
- n the maximum number of log records you want to obtain
rotate log file
Equal to kill -HUP <controller_process_pid>.
http
POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "log_rotate" }
curl
curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "log_rotate"}'
wget
wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "log_rotate"}'
httpie
echo '{
"method": "log_rotate"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/core', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'log_rotate',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with sysfunc=yes permissions
API keys
create API key
API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.
Keys with master permission can not be created.
http
PUT /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true, "allow": "cmd" }
curl
curl -i -X PUT http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"allow": "cmd", "save": true, "sysfunc": true}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"allow": "cmd", "save": true, "sysfunc": true}'
httpie
echo '{
"allow": "cmd",
"save": true,
"sysfunc": true
}' | http PUT http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'allow': 'cmd',
'save': True,
'sysfunc': True,
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [
"cmd"
],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey2",
"items": [],
"key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- API Key API key with master permissions
- save save configuration immediately
Returns:
JSON with serialized key object
delete API key
http
DELETE /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/key/testkey2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
list API key permissions
Lists API key permissons (including a key itself)
Note
API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.
http
GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/key/testkey2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"allow": [
"cmd"
],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey2",
"items": [],
"key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- API Key API key with master permissions
- save save configuration immediately
list API keys
http
GET /r/key HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/key -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/key --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/key X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/key', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"dynamic": false,
"key_id": "masterkey",
"master": true
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": true,
"groups": [
"#"
],
"items": [],
"key_id": "default",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": true,
"device": true,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "lm",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": true,
"lock": true
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "operator",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [
"#"
],
"items": [],
"key_id": "sfa",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [
"item1"
],
"key_id": "t4",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": false,
"groups": [],
"items": [
"sensor:sensors/sensor1"
],
"key_id": "test",
"master": false,
"sysfunc": false
},
{
"allow": {
"cmd": false,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey",
"master": false,
"sysfunc": true
},
{
"allow": {
"cmd": true,
"device": false,
"lock": false
},
"dynamic": true,
"groups": [],
"items": [],
"key_id": "testkey2",
"master": false,
"sysfunc": true
}
]
Parameters:
- API Key API key with master permissions
regenerate API key
http
POST /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "regenerate" }
curl
curl -i -X POST http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "regenerate"}'
wget
wget -S -O- http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "regenerate"}'
httpie
echo '{
"method": "regenerate"
}' | http POST http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'method': 'regenerate',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "3dbcd3d24c6dc878cebe369eb9fdb95ae99fee14e99cdfd911b83629688d2854"
}
Parameters:
- API Key API key with master permissions
Returns:
JSON dict with new key value in “key” field
set API key permissions
http
PATCH /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "save": true, "sysfunc": true }
curl
curl -i -X PATCH http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "sysfunc": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "sysfunc": true}'
httpie
echo '{
"save": true,
"sysfunc": true
}' | http PATCH http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/key/testkey2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'save': True,
'sysfunc': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- p property
- v value (if none, permission will be revoked)
- save save configuration immediately
User accounts
assign API key to user
http
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "a": "masterkey" }
curl
curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "masterkey"}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "masterkey"}'
httpie
echo '{
"a": "masterkey"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'masterkey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- a API key to assign (key id, not a key itself)
create user account
Note
All changes to user accounts are instant, if the system works in read/only mode, set it to read/write before performing user management.
http
PUT /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "verysecretpassword", "a": "testkey" }
curl
curl -i -X PUT http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "testkey", "p": "verysecretpassword"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "testkey", "p": "verysecretpassword"}'
httpie
echo '{
"a": "testkey",
"p": "verysecretpassword"
}' | http PUT http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'a': 'testkey',
'p': 'verysecretpassword',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test2"
}
Parameters:
- API Key API key with master permissions
- p user password
- a API key to assign (key id, not a key itself)
delete user account
http
DELETE /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/user/test2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/user/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get user account info
http
GET /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/user/test2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/user/test2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"key": "testkey",
"user": "test2"
}
Parameters:
- API Key API key with master permissions
list user accounts
http
GET /r/user HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/user -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/user --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/user X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/user', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"key": "test",
"user": "divisor"
},
{
"key": "testkey",
"user": "test"
},
{
"key": "testkey",
"user": "test2"
}
]
Parameters:
- API Key API key with master permissions
set user password
http
PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "p": "qwerty" }
curl
curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"p": "qwerty"}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"p": "qwerty"}'
httpie
echo '{
"p": "qwerty"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/user/test2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'p': 'qwerty',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- p new password
Notifier management
disable notifier
Note
The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.
http
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": false }
curl
curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false}'
httpie
echo '{
"enabled": false
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': False,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
enable notifier
Note
The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.
http
PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "enabled": true }
curl
curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true}'
httpie
echo '{
"enabled": true
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'enabled': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get notifier configuration
http
GET /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/notifier/eva_1 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/notifier/eva_1 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/notifier/eva_1 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/notifier/eva_1', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
Parameters:
- API Key API key with master permissions
list notifiers
http
GET /r/notifier HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/notifier -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/notifier --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/notifier X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/notifier', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
[
{
"db": "db1.db",
"enabled": true,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
}
],
"id": "db_1",
"keep": 86400,
"type": "db"
},
{
"announce_interval": 5.0,
"api_enabled": true,
"enabled": false,
"events": [
{
"groups": [
"#"
],
"subject": "state",
"types": [
"#"
]
},
{
"level": 30,
"subject": "log"
}
],
"host": "mws1-v1",
"id": "eva_1",
"password": "test",
"qos": {
"action": 2,
"log": 2,
"state": 2,
"system": 2
},
"type": "mqtt",
"username": "eva"
}
]
Parameters:
- API Key API key with master permissions
File management
put file to runtime folder
Puts a new file into runtime folder. If the file with such name exists, it will be overwritten. As all files in runtime are text, binary data can not be put.
http
PUT /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "/bin/sh\n\nexit 0", "e": true }
curl
curl -i -X PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true, "m": "/bin/sh\n\nexit 0"}'
wget
wget -S -O- --method=PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true, "m": "/bin/sh\n\nexit 0"}'
httpie
echo '{
"e": true,
"m": "/bin/sh\n\nexit 0"
}' | http PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.put('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': True,
'm': '/bin/sh\n\nexit 0',
})
response
HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"id": "xc/uc/test_action_script2",
"type": "runtime"
}
Parameters:
- API Key API key with master permissions
- m file content
set file exec permission
http
PATCH /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "e": true, "e": true }
curl
curl -i -X PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true}'
wget
wget -S -O- --method=PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true}'
httpie
echo '{
"e": true
}' | http PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'Content-Type': 'application/json',
'X-Auth-Key': 'mykey',
}, json={
'e': True,
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
- e false for 0x644, true for 0x755 (executable)
delete file from runtime folder
http
DELETE /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- --method=DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'
httpie
http DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
python-requests
requests.delete('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Parameters:
- API Key API key with master permissions
get file contents from runtime folder
http
GET /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'
wget
wget -S -O- http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'
httpie
http http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
'X-Auth-Key': 'mykey',
})
response
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"data": "/bin/sh\n\nexit 0",
"e": true,
"file": "xc/uc/test_action_script2"
}
Parameters:
- API Key API key with master permissions
API Clients
All EVA API servers were designed as a simple and user-friendly way to work from a command line using traditional calling methods of Linux http requests: GET, wget, lynx, curl etc. That is why JSON incoming data is always duplicated with the traditional GET/POST request parameters.
API outgoing data is always in JSON format, which can easily be parsed with the use of jq (usually available in all modern Linux distributions), for example:
curl -s 'http://localhost:8812/uc-api/test?k=APIKEY' | jq .version -r
You may call API functions via HTTP GET or HTTP POST - all functions respond similarly regardless of the request method. You may use www-form as well as JSON for POST.
If you want to integrate EVA API in your Python or PHP application, EVA can offer ready-made client libraries.
Contents
EVA JS Framework
EVA JS Framework and EVA JS Toolbox are used to build web browser interfaces with HTML and JavaScript .
Framework also can be used in Node.js apps.
Note
Starting from EVA ICS 3.2.3 JavaScript Framework is not installed by default. Previous EVA SFA Framework is deprecated and no longer supported.
Framework requires fetch function, which is available in all modern web browsers. For old browsers polyfill should be used, unfetch is a recommended one.
API client for Python
API client for Python has already been installed on all EVA servers and is used by the system itself. If you want to use the client module on another system, just create eva/client folder, copy lib/eva/client/apiclient.py file into it and create an empty file __init__.py. Other files in this folder are used by the system for a higher level of access to API, which is not publicly documented.
Example of working with API from Python is located in include/python/ folder of EVA.
API classes for Python
API has two classes:
eva.client.apiclient.APIClient()
and
eva.client.apiclient.APIClientLocal(product, dir_eva=None)
APIClientLocal class may be used on the servers where EVA is installed. When specifying product=’<subsystem code>’ parameter (e.g. product = ‘uc’) API is automatically initialized by loading parameters and keys specifically from configuration files of the controller. If you load the apiclient.py module from lib/eva/client/ folder, it is not necessary to set dir_eva parameter. Otherwise, it should point to EVA root folder.
APIClient class should always be initialized manually.
API requires jsonpickle and requests modules.
API initialization
API is initialized with the use of the following functions:
- set_key(key) set API key.
- set_uri(uri) set the root API URI (i.e., http://localhost:8812). You don’t need to specify the full path to API.
- set_timeout(timeout) set maximum request timeout (seconds), 5 seconds by default.
- set_product(product) set controller type: uc for Universal Controller, lm for Logic Manager, sfa for SCADA Final Aggregator. The client automatically identifies which API is to be called - either SYS API one or the one of the certain controller - that is why this parameter is required.
- ssl_verify(v) to verify or not SSL certificate validity while working through https://. Can be True (check) or False (don’t check). The certificate is verified by default.
Example:
from eva.client.apiclient import APIClient
api = APIClient()
api.set_key(APIKEY)
api.set_uri('http://192.168.0.77:8812')
api.set_product('uc')
API function call
API functions are invoked by calling the call function:
APIClient.call(func, params=None, timeout=None)
where:
- params the dict of the request parameters (if required)
- timeout - maximum time (in seconds) to wait for the API response (if not set - the default timeout is used or the one set during API client initialization).
Example:
from eva.client.apiclient import APIClientLocal
api = APIClientLocal('uc')
code, result = api.call('state', { 'i': 'unit1' })
The function returns a tuple of two variables:
- code API call result
- result the result itself (JSON response converted to Python dict or array).
API result codes
Result codes are stored in module variables (i.e. apiclient.result_ok)
# the call succeeded
result_ok = 0
# the item or resource is not found
result_not_found = 1
# access is denied with the set API key
result_forbidden = 2
# server responded with error http status (e.g. API function crashed)
result_api_error = 3
# unknown error: all errors not listed here fall within this category
result_unknown_error = 4
# API is not initialized - URI is not set
result_not_ready = 5
# Attempt to call undefined API function
result_func_unknown = 6
# server connection failed
result_server_error = 7
# the server request exceeded the time set in timeout
result_server_timeout = 8
# API response cannot be parsed or is invalid
result_bad_data = 9
# API function failed
result_func_failed = 10
# API function is called with invalid params
result_invalid_params = 11
# API function attempted to create resource which already exists and can't
# be recreated until deleted/removed
result_invalid_params = 12
# the resource is busy (in use) and can not be accessed/recreated or
# deleted at this moment
result_busy = 13
# the method is not implemented in/for requested resource
result_not_implemented = 14
In case of error, result is an empty dict or contains field “error” which is filled with error message from server (if available).
JSON RPC API client
As EVA ICS uses standard JSON RPC 2.0 protocol, any 3rd party JSON RPC client may be used. In the example below, we’ll use simple JSON RPC client for Python 3.
Usage example
Let’s call UC API method state and obtain state of sensors:
from jsonrpcclient import request as rpc
r = rpc('http://localhost:8812/jrpc', 'state', k='YOUR_API_KEY', p='sensor')
for s in r.data.result:
print(s['oid'])
Note
If using custom API client, you may still put API key to X-Auth-Key request header. This is against JSON RPC standard, so if you want to keep it right, you must have k in params of each request.
API result codes
JSON RPC API responds in standard JSON RPC way with HTTP code 200 (OK). In case JSON RPC request has no id, no body is returned and HTTP response code will be 202 (Accepted).
In case of API method errors, HTTP code is still 200 (OK). Error codes can be found in the response body.
Developing own PHI (Physical Interface) for EVA ICS. HOWTO
PHI (Physical interface) is a low level driver which communicates directly with an equipment. PHI should not contain any logic, its job is only to get/set an equipment to the state requested by LPI.
Contents
- Developing own PHI (Physical Interface) for EVA ICS. HOWTO
- Required variables in a header
- Classes and modules
- Constructor
- Primary methods
- Parent methods
- Optional methods
- Working with unit values
- Handling events
- Working with I2C/SMBus
- Working with Modbus
- Working with 1-Wire via OWFS
- Working with SNMP
- Working with MQTT
- Working with Modbus slave memory space
- Working with UDP API
- Discovering SSDP hardware
- Asynchronous I/O
- Exceptions
- Testing
Required variables in a header
PHI info
- __author__ module author
- __copyright__ copyright
- __license__ module license
- __version__ module version
- __description__ module description (keep it short)
PHI system info
the next fields are processed by controller, so make them exactly as required
- __equipment__ supported equipment (list or string)
- __api__ module API (integer number), current is 5
- __required__ features required from LPI (Logical to Physical Interface, list):
- aao_get get and process all ports at once
- aao_set set all ports at once
- action unit actions
- events event processing
- port_get get single port data
- port_set set single port data
- status process item status
- value process item values
- __mods_required__ required python modules (not included neither in standard Python install nor in EVA ICS)
- __lpi_default__ if specified, the default driver will be created for this PHI when loaded.
- __features__ own features provided (list, features from __required__ are automatically included):
- aao_get PHI can return state of all ports at once but can work with a single ports as well
- aao_set PHI can set state of all ports at once but can work with a single ports as well
- universal PHI is universal and process cfg in requests.
- cache PHI supports state caching (useful for slow devices)
- __discover__ string or list, which describes how “discover” method (if implemented) will search for the equipment: net for network or EVA ICS bus name (modbus, owfs etc.)
PHI help
Each PHI module should contain 4 help variables:
- __config__help__ module configuration help (on load)
- __get_help__ additional configuration params possible for LPI to send with get command
- __set_help__ additional configuration params possible for LPI to send with set command
- __discover_help help for “discover” method
First variable should be human readable, others may copy, join or process the first one or each other in any way.
All variables should be in list format, containing dictionaries with the following context:
- name property name
- help property description (help)
- type property type
- required True if property is required, False if it’s optional
Property type may be:
- bool boolean (True/False)
- str string
- url string containing url
- int integer
- uint unsigned integer (greater or equal to 0)
- hex hexadecimal number
- bin binary number
- float float number
- ufloat unsigned float (greater or equal to 0)
- list:type list of variables with type specified
- enum:type:a,b,c list of the permitted specified type values
If the property accepts multiple types, they should be listed via or (|) symbol.
The last one variable is
- __help__
It should contain the extended PHI description and operation manual. May be in any variable format and use restructured text directives for formatting.
Classes and modules
It’s allowed to import any Python system module or module installed by EVA ICS. If PHI requires installing more modules, they should be listed in PHI help file and in __mods_required__ variable.
Warning
All non-standard modules (not included neither in Python install nor in EVA ICS) should be imported with try/catch with importlib, their unavailability shouldn’t block loading PHI for informational puproses.
Importing modules eva.uc.drivers.tools, eva.tools, eva.traphandler, eva.uc.modbus, eva.uc.smbus and functions from eva.uc.driverapi:
- get_version() get Driver API version
- get_polldelay() get EVA poll delay
- get_timeout() get default timeout
- get_system_name() get system name
- critical() send EVA critical call
- log_traceback() log traceback debug info
- lock(l, timeout, expires) acquire lock “eva:phi:l”, wait max timeout sec, lock automatically expires in expires sec. Timeout and expiration time can’t be longer than default controller timeout.
- unlock(l) release lock “eva:phi:l”
- handle_phi_event(phi, port, data) ask Driver API to handle event (see below)
is highly welcome. Importing other EVA modules or driverapi functions is not recommended unless you really know what you do.
The main class is defined as:
from eva.uc.drivers.phi.generic_phi import PHI as GenericPHI
from eva.uc.driverapi import phi_constructor
class PHI(GenericPHI):
#<your code>
Constructor
The constructor should set the above constants to class variables to let them be serialized by parent class if requested:
@phi_constructor
def __init__(self, **kwargs):
# your code, e.g. parsing self.phi_cfg
Decorator @phi_constructor automatically invokes parent constructor and handles special init requests.
If the constructor faces a problem (e.g. parsing a config or checking equipment, e.g. local bus) it may set self.ready=False to abort controller loading the module.
If PHI methods get/set can’t work with single ports at all (e.g. equipment returns state of all ports at once only), constructor should set variables:
The parent constructor sets the variable self.phi_cfg to phi_cfg or to {}, so it’s safe to work with it with self.phi_cfg.get(cfgvar).
Primary methods
The following methods should be defined. cfg param may contain configuration params which should override the default ones for the current call.
# if PHI can read data from the equipment
def get(self, port=None, cfg=None, timeout=0):
#<your code>
#should return a single state value or a dict { 'port': value }
#port should always be a string
#
#should return None if failed, integer for status, string for values
#
#if PHI supports aao_get feature, it should return all port states when
#no port is specified in request.
# if PHI can write data to the equipment
def set(self, port=None, data=None, cfg=None, timeout=0):
#<your code>
#should return True (or result) if passed, False or None if failed
#
#If PHI supports aao_set feature, it should deal with a list of ports,
#if no - with a single port only. If both port_set and aao_set are
#specified in features, PHI should deal with both single port and list
#of ports
Note
If unit action is called without value, PHI set method is called with previous known unit value
port and data may be integers, string, contain lists or be set as None. PHI should always be ready to any incoming params and handle the missing or incorrect by itself. If port contains a list, data always contain a list too.
cfg may contain equipment configuration options. If the driver is universal, it should handle them properly.
Warning
watch out for the timeout - if it’s expired, the controller may crash or be forcedly restarted. Always calculate the remaining time for the external calls and return error as soon as it comes closer to expiration.
Method test should perform a self-test (equipment test) if cmd==’self’, other methods are variable and may be used e.g. for debugging. If command is not understood by the method, it’s a rule of good taste to return a help text (dict { ‘command’: ‘command help’ }).
def test(self, cmd=None):
#<your code>
Method exec may be implemented to perform some actions on the equipment, e.g. changing the equipment settings or manage the firmware. You can implement any commands in any form you wish using cmd and args params.
def exec(self, cmd=None, args=None):
#<your code>
The method should be used for real commands only, all the tests (e.g. testing get method, obtaining equipment info for testing or informational purposes) should be implemented in test. After the command execution, the method should return OK on success or FAILED on failure. If command is not understood by the method, it’s a rule of good taste to return a help text (dict { ‘command’: ‘command help’ }).
The following methods may be used to call or register/unregister anything on driver load/unload:
def start(self):
#<your code>
def stop(self):
#<your code>
def unload(self):
# called when PHI is unloaded from the controller
#<your code>
Parent methods
Parent class provides the following useful functions:
- self.set_cached_state(data) set driver cached state (any format)
- self.get_cached_state() return the state cached before. If the cache is expired (self.cache param handled by parent), the method return None
Warning
If get_cached_state() method is used, PHI should return a copy of cached object
All the logging should be done with the following methods:
- self.log_debug(msg)
- self.log_info(msg)
- self.log_warning(msg)
- self.log_error(msg)
- self.log_critical(msg)
- self.critical(msg)
The last two methods do the same, logging an event and calling controller critical() method.
Optional methods
get_phi_ports
The method should be implemented if you want to let PHI to respond to API “get_phi_ports” method.
def get_ports(self):
#<your code>
The method should return list of dictionaries with “port”, “name” and “description” fields. Are fields are required and should be strings.
If hardware equipment always has fixed amount of ports and they all are used for the same purpose (e.g. relay), you may use parent function generate_port_list:
def get_ports(self):
return self.generate_port_list(
port_max=16, description='relay port #{}')
# parent function has the following params:
# def generate_port_list(
# port_min=1, port_max=1, name='port #{}', description='port #{}')
discover
The method should be implemented if you want let PHI to respond to API “phi_discover” method and should return all supported equipment discovered, including parameters for PHI loading.
“discover” method should be always implemented as static as it is always called on module, before PHI is loaded and primary class is created. If PHI implements discovery, __discover__ header should always be present in module.
__discover__ = 'net'
# ............
@staticmethod
def discover(interface=None, timeout=0):
# interface - network or bus name, can be list or string
#<your code>
The method should return array of dictionaries, which may contain any fields. Field !load is required and should contain dictionary with PHI loading params, e.g. { ‘host’: ‘<ip_of_hardware>’ }.
You may specify result column ordering for EVA ICS interfaces. For that, a special record:
[{ '!opt': 'cols', 'value': [<columns>]}]
must be present as first in a result. A special column ‘!load’ in a column list is not required.
Working with unit values
For units, method get can return either single integer (status) or a state tuple (status, value). If value is set to None, it is ignored and only status is updated. LPI automatically detects output data and parses either status or (status, value) pair.
For method set, by default data contains either status (integer) or a list of integers only. To accept extended state (status, value tuple or a list of tuples) for set, value string must be specified in __required__ header list variable.
Handling events
Incoming events
If the equipment sends any event, PHI should ask Driver API to handle it. This can be done with method
eva.uc.driverapi.handle_phi_event(phi, port, data)
where:
- phi = self
- port = port, where the event has happened
- data = port state values, as much as possible (dict {‘port’: state })
The controller will call update() method for all items using the caller PHI for updating, providing LPIs state data to let them process the event with minimized amount of additional PHI.get() calls.
Value -1 can be used to set unit error status, value False to set sensor error status.
SNMP traps
First you need to subscribe to EVA trap handler. Import eva.traphandler mod and modify PHI start and stop methods:
import eva.traphandler
class PHI(GenericPHI):
# class code
def start(self):
#<your code>
eva.traphandler.subscribe(self)
def stop(self):
#<your code>
eva.traphandler.unsubscribe(self)
EVA trap handler calls method process_snmp_trap(data) for each object subscribed, so let’s create it inside a primary class:
def process_snmp_trap(self, host, data):
#<your code>
host IP address of the host where SNMP trap is coming from.
data a dict with name/value pairs, where name is SNMP numeric OID without a first dot, and value is always a string. Check if this trap belongs to your device and perform the required actions. Don’t worry about the timeout (except for the actual reaction time on a trap event) because every method is being executed in its own thread.
EVA traphandler doesn’t care about the method return value and you must process all the errors by yourself.
Schedule updates
If the equipment doesn’t send any events, PHI can initiate updating the items by itself. To perform this, PHI should support aao_get feature and be loaded with update=N config param. Updates, intervals as well as the whole update process are handled by parent class.
Working with I2C/SMBus
It’s highly recommended to use internal UC locking for I2C bus. Then you can use any module available to work with I2C/SMBus. As there are a lot of modules with similar functions, you can choose it on your own. See the code example below:
# ...........
# we'll use smbus2 module in this example
__mods_required__ = ['smbus2']
# ...........
# import i2c locker module
import eva.uc.i2cbus
@phi_constructor
def __init__(self, **kwargs):
# code
try:
self.smbus2 = importlib.import_module('smbus2')
except:
self.log_error('unable to load smbus2 python module')
self.ready = False
return
def get(self, port=None, cfg=None, timeout=0):
if not eva.uc.i2cbus.lock(self.bus):
self.log_error('unable to lock I2C bus')
return None
bus = self.smbus2.SMBus(self.bus)
# perform some operations, then release the bus for other threads
eva.i2cbus.release(self.bus)
return result
All I2C/SMBus exceptions, timeouts and retries should be handled by the code of your PHI.
Working with Modbus
Working with Modbus is pretty easy. PHIs don’t need to care about the Modbus connection and data exchange at all, everything is managed by eva.uc.modbus module.
# everything you need is just import module
import eva.uc.modbus as modbus
@phi_constructor
def __init__(self, **kwargs):
# ....
# it's recommended to force aao_get in Modbus PHI to let it read states
# with one modbus request
self.modbus_port = self.phi_cfg.get('port')
# check in constructor if the specified modbus port is defined
if not modbus.is_port(self.modbus_port):
self.log_error('modbus port ID not specified or invalid')
self.ready = False
return
# store unit id PHI is loaded for
try:
self.unit_id = int(self.phi_cfg.get('unit'))
except:
self.ready = False
return
def get(self, port=None, cfg=None, timeout=0):
# modbus.get_port(port_id) function returns:
# False - if port failed to connect,
# None - if port doesn't exist or may exceed the timeout,
# 0 - if port is locked and busy,
# or the port object itself
mb = modbus.get_port(self.modbus_port, timeout)
if not mb: return None
# The port object is a regular pymodbus object
# (https://pymodbus.readthedocs.io) and supports all pymodbus functions.
# All the functions are wrapped with EVA modbus module which handles
# all errors and retry attempts. The ports PHI gets are always in the
# connected state.
r = mb.read_coils(0, 16, unit=self.unit_id)
# Release modbus port as soon as possible to let other components work
# with it while your PHI is processing the data
mb.release()
# result is a regular pymodbus result
if rr.isError(): return None
# let's convert 16 coils to 16 port states
result = {}
try:
for i in range(16):
result[str(i + 1)] = 1 if rr.bits[i] else 0
except:
result = None
return result
The variable client_type of the port object (mb.client_type) holds the port type (tcp, udp, rtu, ascii or binary). This can be used to make PHI work with the equipment of the same type which uses e.g. different registers for different connection types.
Working with 1-Wire via OWFS
As EVA ICS has virtual OWFS buses, you don’t need to initialize OWFS by yourself.
Methods available:
- owfs.is_bus(bus_id) returns True if bus is defined
- bus = owfs.get_bus(bus_id) get bus. If locking is defined, the bus becomes exclusively locked.
- bus.read(path, attr) read equipment attribute value
- bus.write(path, attr, value) write equipment attribute value
- bus.release() Release bus. As bus may be locked for others, the method should be always called immediately after the work with bus is finished.
# everything you need is just import module
import eva.uc.owfs as owfs
@phi_constructor
def __init__(self, **kwargs):
# ....
# it's recommended to force aao_get in Modbus PHI (list it in
# __required__) to let it read states # with one modbus request
self.owfs_bus = self.phi_cfg.get('owfs')
# check in constructor if the specified modbus port is defined
if not owfs.is_bus(self.owfs_bus):
self.log_error('owfs bus ID not specified or invalid')
self.ready = False
return
# store path of equipment PHI is loaded for
self.path = self.phi_cfg.get('path')
if not self.path:
self.log_error('owfs path is not specified')
self.ready = False
return
def get(self, port=None, cfg=None, timeout=0):
bus = owfs.get_bus(self.owfs_bus)
if not bus: return None
try:
value = bus.read(path, 'temperature')
if not value:
raise Exception('can not obtain temperature value')
return {'temperature': value}
except:
return None
finally:
bus.release()
Working with SNMP
EVA ICS has bindings to primary pysnmp methods, which can be found in eva.uc.drivers.tools.snmp module. Pysnmp is a reach-feature SNMP module and is included in setup by default, however this module is not recommended to use on a slow hardware in production.
The rule of good taste is to check if alternative (faster) SNMP module is present (such as e.g. python3-netsnmp) and use it for a regular get/set functions instead:
import eva.uc.drivers.tools.snmp as snmp
try:
import netsnmp
except:
netsnmp = None
#....................................
#....................................
#....................................
if netsnmp:
# ... use netsnmp module
else:
# ... use default pysnmp module
Working with MQTT
The best way to work with MQTT is to use EVA ICS notification system connections. Instead of creating own MQTT connection and manage topics, let EVA core do its job. If your equipment and EVA ICS use different MQTT servers, just create new MQTT notifier to equipment server in EVA ICS without any subscriptions.
Note
If space is specified in EVA MQTT notifier, all topics should be relative, e.g. if space=test, MQTT can send and subscribe only to topics below the space level: equipment1/POWER will send/subscribe to test/equipment1/POWER.
Use eva.uc.drivers.tools.mqtt.MQTT class to deal with notifiers. If no notifier_id is specified eva_1 notifier is used.
Warning
MQTT custom handlers may be started in different threads. Don’t forget to use locking mechanisms if required.
Let’s deal with an equipment which has MQTT topic topic/POWER with values ON/OFF:
# everything you need is just import class
from eva.uc.drivers.tools.mqtt import MQTT
# and a function to handle events
from eva.uc.driverapi import handle_phi_event
@phi_constructor
def __init__(self, **kwargs):
# ....
self.topic = self.phi_cfg.get('t')
self.mqtt = MQTT(self.phi_cfg.get('n'))
self.current_status = { '1': None }
if self.topic is None or self.mqtt is None:
self.ready = False
def get(self, port=None, cfg=None, timeout=0):
# as we can not query equipment, return saved status instead
return self.current_status
def set(self, port=None, data=None, cfg=None, timeout=0):
# .... check data, prepare
try:
state = int(data)
except:
return False
# then use MQTT.send function to send data to desired topic
self.mqtt.send(self.topic + '/POWER', 'ON' if state else 'OFF')
return True
def start(self):
# register a custom handler for MQTT topic
self.mqtt.register(self.topic + '/POWER', self.mqtt_handler)
def stop(self):
# don't forget to unregister a custom handler when PHI is unloaded
self.mqtt.unregister(self.topic + '/POWER', self.mqtt_handler)
def mqtt_state_handler(self, data, topic, qos, retain):
# update current status
self.current_status['1'] = 1 if data == 'ON' else 0
# then handle PHI event
handle_phi_event(self, 1, self.get())
Working with Modbus slave memory space
Universal Controller can perform basic data processing as Modbus slave, custom PHI can do this more flexible. E.g. there’s temperature sensor, which reports its value multiplied by 100. As Modbus registers don’t support floats, custom PHI module can listen to the register and automatically divide value by 100 before sending update to UC item.
Multiple items and PHIs can watch the same register and perform data processing independently.
import eva.uc.modbus as modbus
@phi_constructor
def __init__(self, **kwargs):
# ....
def start(self):
# watch changes of Modbus slave register
# addr - value from 0 to 9999
# self.process_modbus - function to process Modbus data
# register - 'h' for holding (default), 'i' for input,
# 'c' for coil and 'd' for discrete input
modbus.register_handler(addr, self.process_modbus, register='h')
def stop(self):
# don't forget to unregister handler when PHI is unloaded
modbus.unregister_handler(addr, self.process_modbus, register='h')
def process_modbus(self, addr, values):
# the function is called as soon as watched Modbus register is changed
# parameters: addr - memory address, values - values written (list)
#
# values of holding and input registers are arrays of 2-byte integers
# values of coils and discrete inputs - arrays of booleans (True/False)
#
# as input registers and discrete inputs are read-only for external
# devices, they can be changed only by another local PHI module or UC
# itself
#
_data = values[0]
self.log_debug('got data: {} from {}'.format(_data, addr))
# process the data
# ...
PHI can also manipulate data in Modbus slave memory blocks manually, to do this use functions:
get_data(addr, register='h', count=1)
# and
set_data(addr, values, register='h')
# ("values" should be a list (of unsigned integers or booleans, depending
# on memory block type)
Working with UDP API
You may use EVA UDP API to receive custom UDP packets and then parse them in PHI. This allows to create various hardware bridges e.g. from 315/433/866 MHz radio protocols, obtaining radio packets with custom programmed hardware appliance and then send them to EVA ICS to handle.
Custom packet format is (\x = hex):
\x01 HANDLER_ID \x01 DATA
DATA is always transmitted to handler in binary format. UDP API encryption, authentication and batch commands in custom packets are not supported (unless managed by handler).
Warning
UDP API custom handlers may be started in different threads. Don’t forget to use locking mechanisms if required.
import eva.udpapi as udp
@phi_constructor
def __init__(self, **kwargs):
# ....
def start(self):
# subscribe to UDP API using PHI ID as handler ID
udp.subscribe(__name__, self.udp_handler)
def stop(self):
# don't forget to unsubscribe when PHI is unloaded
udp.unsubscribe(__name__, self.udp_handler)
def udp_handler(self, data, address):
_data = data.decode()
self.log_debug('got data: {} from {}'.format(_data, address))
# process the data
# ...
Discovering SSDP hardware
If “discover” method is implemented and discovers hardware equipment via SSDP, driver tool can be used:
def discover(interface=None, timeout=0):
import eva.uc.drivers.tools.ssdp as ssdp
result = ssdp.discover(
'upnp:all',
interface=interface,
timeout=timeout,
discard_headers=[
'Cache-control', 'Ext', 'Location', 'Host'
])
# if upnp:all is used - filter result to leave only supported hardware
# eva.uc.drivers.tools.ssdp.discover function has the following params:
# def discover(st,
# ip='239.255.255.250',
# port=1900,
# mx=True,
# interface=None,
# trailing_crlf=True,
# parse_data=True,
# discard_headers=['Cache-control', 'Host'],
# timeout=None)
# where
# mx send MX header or not
# trailing_crlf append trailing CR/LF at the end of request
# parse_data try parsing data automatically
# discard_headers discard specified headers if data is parsed
Asynchronous I/O
Calls to PHIs are always synchronous. If equipment can set multiple ports at once or PHI can provide asynchronous features itself, it should have aao_get/aao_set in __features__ or __required__ lists.
The difference between last two is that __required__ requires parent LPI to have a feature for working with multiple ports at once and PHI get/set methods always get list of ports/data.
While __features__ allows LPI to send multi-port command, however it can be single as well. In this case get/set methods of PHI should manually check incoming data format (single value or list).
You, as PHI developer, always choose by yourself the way how to work with multiple hardware ports at once: get/set multiple registers or special “group” registers (e.g. for Modbus or SNMP), use asynchronous HTTP API calls or launch multiple threads. However, using aao_get/aao_set is always good practice and recommended if possible.
Exceptions
The methods of PHI should not raise any exceptions and handle/log all errors by themselves.
Testing
Use bin/test-phi command-line tool to perform PHI module tests. The tool requires test scenario file, which may contain the following functions:
- debug() turn on debug mode (verbose output), equal to -D command-line option
- nodebug() turn off debug mode
- modbus(params) create virtual Modbus port with ID default
- load(phi_mod, phi_cfg=None) load PHI module for tests. PHI cfg may be specified either as string or as dictionary
- get(port=None, cfg=None, timeout=None) call PHI get function
- set(port=None, data=None, cfg=None, timeout=None) call PHI set function
- test(cmd=None) call PHI test function
- exec(cmd=None, args=None) call PHI exec function
- sleep(seconds) delay execution for a given number of seconds (alias for time.sleep)
additionally, each function automatically prints the result. Test scenario is actually a Python code and may contain any Python logic, additional module imports etc.
Example test scenario. Let’s test dae_ro16_modbus module:
debug()
modbus('tcp:192.168.55.11:502')
load('dae_ro16_modbus', 'port=default,unit=1')
if test('self') != 'OK': exit(1)
set(port=2,data=1)
set(port=5,data=1)
get()
set(port=2,data=0)
Macro extensions
As macros are written in Python, you can use any Python module to extend your macros. Additionally Logic Manager has ability to extend macros with extensions.
Modules are more flexible and are a standard Python way to extend your software. However macro extensions are more simple, standardized and easy to configure. As the goal is to keep macro code as simple as possible, macro extensions are the best choice in many cases.
Contents
Loading macro extension
Macro extensions are stored in xc/extensions folder. To list available macro extension modules, use command:
eva lm ext mods
Next command returns extension info:
eva lm ext modinfo <ext_module>
To get information about extension configuration and functions provided, use commands:
eva lm ext modhelp <ext_module> cfg
eva lm ext modhelp <ext_module> functions
To load/unload macro extension, use command:
# load
eva lm ext load [-c CONFIG] [-y] <ext_id> <ext_module>
# unload
eva lm ext unload <ext_id>
where:
- -c CONFIG extension configuration options, comma separated
- -y save extension config after successful load
Extension functions
When extension is loaded, its functions become available in all macros automatically with names <ext_id>_<function>.
E.g. when extension audio is loaded with ID a1, its function play is available as a1_play. This allows you to load one extension multiple times and have different functionality according to specified configuration without need to configure module/class params in macros.
If you want to make a short alias for extension function, use alias (e.g. in xc/lm/common.py):
alias('play', 'a1_play')
Unlike play=a1_play alias doesn’t throw an exception and let macros work even if extension is failed to load or its functions are not available.
Included extensions
The following extensions are included in EVA ICS distribution by default:
- audio plays audio files
- rpush notifications via Roboger (https://www.roboger.com/, https://github.com/alttch/roboger)
- run_remote execute macro on any remote Logic Manager
- tts Text-to-speech engine via Altertech TTS Broker (https://pypi.org/project/ttsbroker/)
Developing your own extension
Create new Python file in xc/extensions folder.
Required variables in a header
- __author__ module author
- __copyright__ copyright
- __license__ module license
- __version__ module version
- __description__ module description (keep it short)
- __api__ module API (integer number), current is 5
- __mods_required__ required python modules (included neither in standard Python install nor in EVA ICS)
- __config__help__ module configuration help (on load)
- __functions__ exported functions
- __help__ should contain the extended description and operation manual. May be in any variable format and use restructured text directives for formatting.
Configuration variable
Configuration variable (__config_help__) should be in list format, containing dictionaries with the following context:
- name property name
- help property description (help)
- type property type
- required True if property is required, False if it’s optional
Property type may be:
- bool boolean (True/False)
- str string
- url string containing url
- int integer
- uint unsigned integer (greater or equal to 0)
- hex hexadecimal number
- bin binary number
- float float number
- ufloat unsigned float (greater or equal to 0)
- list:type list of variables with type specified
- enum:type:a,b,c list of permitted specified type values
If a property accepts multiple types, they should be listed via or (|) symbol.
Exported functions
Exported functions (__functions__) variable is a dictionary in format:
{ 'function(params)': 'description' }
# e.g.
{
'func1(param1, param2=0, param3=True)': 'This function does something',
'func2(param1=0)': 'This function does something else'
}
All exported functions should be defined in a primary extension class.
Classes and modules
It’s allowed to import any Python system module or module installed by EVA ICS. If extension requires installing more modules, they should be listed in extension help and in __mods_required__ variable.
Warning
All non-standard modules (not included neither in Python install nor in EVA ICS) should be imported with try/catch with importlib, their unavailability shouldn’t block loading extension for informational purposes.
Importing EVA modules and functions from eva.lm.extapi:
- get_version() get Extension API version
- get_polldelay() get EVA poll delay
- get_timeout() get default timeout
- critical() send EVA critical call
- log_traceback() log traceback debug info
is highly welcome.
The main class is defined as:
from eva.lm.extensions.generic import LMExt as GenericExt
from eva.lm.extapi import ext_constructor
class LMExt(GenericExt):
#<your code>
Constructor
The constructor should set the above constants to class variables to let them be serialized by parent class if requested:
@ext_constructor
def __init__(self, **kwargs):
# your code, e.g. parsing self.cfg
Decorator @ext_constructor automatically invokes parent constructor and handles special init requests.
If the constructor faces a problem (i.e. parsing a config or checking required modules) it may set self.ready=False to abort controller loading the extension.
Exceptions
There’s no standard way to handle exceptions, however if any of exported functions raise them, this should be specified in extension help and readme file.
Testing
Use bin/test-ext command-line tool to perform PHI module tests. The tool requires test Python file, which loads extension as _ and contains all its functions (e.g. __test for extension.test):
print('Testing extension')
__test(params)
__func2(params)
__func3(params)
print('Test completed')