API reference
Framework
- $eva.action.exec(oid, params, wait)
Call unit action
- Arguments:
oid (
string()
) – unit OIDparams (
object()
) – action paramswait (
boolean()
) – wait until the action is completed (default: true)
- Async:
Async function/Promise
- $eva.action.kill(oid)
Terminate all unit actions
- Arguments:
oid (
string()
) – unit OID
- Async:
Async function/Promise
- $eva.action.run(oid, params, wait)
Run lmacro
- Arguments:
oid (
string()
) – lmacro oidparams (
object()
) – call paramswait (
boolean()
) – wait until completed (default: true)
- Async:
Async function/Promise
- $eva.action.start(oid, wait)
Call unit action with status=1
- Arguments:
oid (
string()
) – unit OIDwait (
boolean()
) – wait until the action is completed (default: true)
- Async:
Async function/Promise
- $eva.action.stop(oid, wait)
Call unit action with status=0
- Arguments:
oid (
string()
) – unit OIDwait (
boolean()
) – wait until the action is completed (default: true)
- Async:
Async function/Promise
- $eva.action.terminate(uuid)
Terminate a unit action
- Arguments:
uuid (
string()
) – action uuid
- Async:
Async function/Promise
- $eva.action.toggle(oid, wait)
Call unit action to toggle its status
- Arguments:
oid (
string()
) – unit OIDwait (
boolean()
) – wait until the action is completed (default: true)
- Async:
Async function/Promise
- $eva.call(func, p1, p2)
Call API function
Calls any available SFA API function
- Arguments:
arguments – item OID (if required), API call params
- Returns:
Promise object
- Async:
Async function/Promise
- $eva.erase_token_cookie()
Erase auth token cookie
It is recommended to call this function when login form is displayed to prevent old token caching
- $eva.get_mode()
Get framework engine mode
- Returns:
“js” or “wasm”
- $eva.interval(i, value)
Set intervals
- Arguments:
i (
string()
) – interval, possible values: ajax_reload, heartbeat, log_reload, reload, restartvalue (
number()
) – interval value (in seconds)
- $eva.log_level(log_level)
Change log processing level
- Arguments:
log_level (
number()
) – log processing level
- $eva.log_start(log_level)
Start log processing
Starts log processing. Framework class must be already logged in.
- Arguments:
log_level (
number()
) – log processing level (optional)
- $eva.lvar.clear(oid)
Clear lvar (set status to 0)
- Arguments:
oid (
string()
) – lvar oid
- Async:
Async function/Promise
- $eva.lvar.decr(oid)
Decrement lvar value
- Arguments:
oid (
string()
) – lvar oid
- Returns:
the new value
- Async:
Async function/Promise
- $eva.lvar.expires(lvar_oid)
Get lvar expiration time left
- Arguments:
lvar_oid (
string()
) – lvar OID
- Returns:
seconds to expiration, -1 if expired, -2 if stopped
- $eva.lvar.incr(oid)
Increment lvar value
- Arguments:
oid (
string()
) – lvar oid
- Returns:
the new value
- Async:
Async function/Promise
- $eva.lvar.reset(oid)
Reset lvar (set status to 1)
- Arguments:
oid (
string()
) – lvar oid
- Async:
Async function/Promise
- $eva.lvar.set(oid, status, value)
Set lvar state
- Arguments:
oid (
string()
) – lvar oidstatus (
numberr()
) – lvar statusvalue – lvar value
- Async:
Async function/Promise
- $eva.lvar.set_status(oid, status)
Set lvar status
- Arguments:
oid (
string()
) – lvar oidstatus (
number()
) – lvar status
- Async:
Async function/Promise
- $eva.lvar.set_value(oid, value)
Set lvar value
- Arguments:
oid (
string()
) – lvar oidvalue – lvar value
- Async:
Async function/Promise
- $eva.lvar.toggle(oid)
Toggle lvar status
- Arguments:
oid (
string()
) – lvar oid
- Async:
Async function/Promise
- $eva.on(event, func)
Set event handler function
A single kind of event can have a single handler only
- Arguments:
event (
string()
) – event, possible values: login.success, login.failed, ws.event, server.reload, server.restart, heartbeat.success, heartbeat.error, log.record, log.postprocess, login.otp_required, login.otp_invalid, login.otp_setupfunc (
function()
) – function called on event
- $eva.restart()
Restart the Framework
e.g. used on heartbeat error or if subscription parameters are changed
- $eva.set_normal(u, p, xopts)
Ask server to return the token to normal mode
(EVA ICS 3.3.2+)
- Arguments:
u (
string()
) – loginp (
string()
) – passwordxopts (
object()
) – extra options (e.g. OTP)
- Async:
Async function/Promise
- $eva.set_readonly()
Ask server to set the token read-only (e.g. after idle)
(EVA ICS 3.3.2+)
the current mode can be obtained from $eva.server_info.aci.token_mode
- Async:
Async function/Promise
- $eva.sleep(sec)
Sleep the number of seconds
- Arguments:
sec (
number()
) – seconds to sleep
- Async:
Async function/Promise
- $eva.start()
Start the Framework
After calling the function authenticates user, opens a WebSocket (in case of WS mode) or schedule AJAXs refresh interval.
- $eva.state(oid)
Get item state
- Arguments:
oid (
string()
) – item OID
- Returns:
state object or undefined if no item found
- $eva.status(oid)
Get item status
- Arguments:
oid (
string()
) – item OID
- Returns:
item status(int) or undefined if no object found
- $eva.stop(keep_auth)
Stop Framework
After calling the function closes open WebSocket if available, stops all workers then tries to close the server session
- Arguments:
keep_auth (
boolean()
) – keep authentication cookies and token
- Returns:
Promise object
- Async:
Async function/Promise
- $eva.system_name()
Get system name
- Returns:
the system name or null if the framework is not logged in
- $eva.unwatch(oid, func)
Stop watching item state updates
If item oid or function is not specified, all watching functions are removed for a single oid (mask) or for all the items watched.
- Arguments:
oid (
string()
) – item oid (e.g. sensor:env/temp1, or sensor:env/*)func (
function()
) – function to be removed
- $eva.value(oid)
Get item value
- Arguments:
oid (
string()
) – item OID
- Returns:
item value or undefined if no item found
- $eva.watch(oid, func, ignore_initial)
Watch item state updates
Registers the function to be called in case of state change event (or at first state load).
If state is already loaded, function will be called immediately. One item (or item mask, set with “*”) can have multiple watchers.
- Arguments:
oid (
string()
) – item oid (e.g. sensor:env/temp1, or sensor:env/*)func (
function()
) – function to be calledignore_initial (
boolean()
) – skip initial state callback
- $eva.watch_action(uuid, func)
Watch action state by uuid
Registers the function to be called in case of action status change event (or at first state load).
If status is already loaded, function will be called immediately. Otherwise status is polled from the server with “action_watch” interval (default: 500ms).
There is no unwatch function as watching is stopped as soon as the action is completed (or server error is occurred)
- Arguments:
uuid (
string()
) – action uuidfunc (
function()
) – function to be called
Toolbox
- $eva.toolbox.animate(ctx)
Animate html element block
Simple loading animation
- Arguments:
ctx (
string or object()
) – DOM element (or id)
- $eva.toolbox.chart(ctx, cfg, oid, params)
Display a chart
If multiple timeframes and multiple items are specified, chart data is filled as: first timeframe for all items, second timeframe for all items etc.
- Arguments:
ctx (
string or object()
) – html container element or id to draw in (must have fixed width/height)cfg (
object()
) – Chart.js configuration (Chart.js v4)oid (
string or array()
) – item oid or oidsparams (
object()
) –object with props
timeframe - timeframe to display (5T - 5 min, 2H - 2 hr, 2D - 2 days etc.), default: 1D. To display past timeframes, use two values, separated with “:”, e.g. 2D:1D - get data for yesterday. To display multiple timeframes, send this param as array. Axis X is always formed from the first timeframe. If you want to change this, put “t” before the necessary timeframe, e.g.: t2D:1D
fill - precision[:np] (10T - 60T recommended, more accurate - more data), np - number precision, optional. default: 30T:2
update - update interval in seconds. If the chart container is no longer visible, chart stops updating
prop - item property to use (default is value)
units - data units (e.g. mm or °C)
args - additional API options (state_history)
- Returns:
chart object
- $eva.toolbox.popup(ctx, pclass, title, msg, params)
Popup window
Opens popup window.
There can be only one popup opened using the specified html ctx. If the page wants to open another popup, the current one is overwritten unless its pclass is higher than a new one.
- Arguments:
ctx (
string or object()
) – html element to use as popup (any empty <div /> is fine)pclass (
string()
) – popup class: info, warning or error. opens a large popup window if ‘!’ is put before the class (e.g. !info)title (
string()
) – popup window titlemsg (
string()
) – popup window messageparams (
object()
) –object with handlers and additional parameters:
ct - popup auto close time (sec), equal to pressing escape
btn1 - button 1 name (default: ‘OK’) btn2 - button 2 name
va - validate function which is executed before Promise resolves. If the function returns true, the popup is closed and resolve function is executed. The function is commonly used to validate input if popup contains input fields.
- Returns:
Promise object. Resolve and reject functions are called with “true” parameter if button is pressed by user.
- Async:
Async function/Promise