Skip to content
New JS Framework for EVA ICS. Supports web browser and CLI (e.g. Node.js)
JavaScript CSS Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
framework
full
toolbox
.gitignore
LICENSE
Makefile
README.md

README.md

JavaScript Framework for EVA ICS

JavaScript Framework for EVA ICS - open source platform for home and industrial IoT.

The library works both in web browsers and Node.js.

Installation

For web browsers

Download

Framework only:

https://raw.githubusercontent.com/alttch/eva-js-framework/master/dist/eva.framework.min.js

Framework with chart and other utility functions:

https://raw.githubusercontent.com/alttch/eva-js-framework/master/dist/eva.min.js

For Node.js

  npm i @eva-ics/framework
  // additional utility functions
  npm i @eva-ics/toolbox

Description of utility functions can be found in EVA ICS toolbox help.

Examples

Initialization

Init (for Node.js):

eva_framework = require('@eva-ics/framework');

// default object
$eva = eva_framework.$eva;

// or for multiple targets
// $eva = new eva_framework.EVA();

Init (for web browsers):

  <script src="eva.framework.min.js"></script>

Configuration

$eva.login = 'operator';
$eva.password = '123';

// not required for web browsers
$eva.api_uri = 'http://localhost:8828';

// turn on debug mode
// $eva.debug = true;

$eva.on('login.success', function() {
  // called when login is successful, states and server info are loaded
});

$eva.on('login.failed', function(err) {
  // do some stuff
  console.log('LOGIN FAILED');
  // login failed not due to invalid credentials - will retry soon
  if (err.code != 2) {
    setTimeout(function(){$eva.start()}, 2000);
  }
});

// start framework and log in
$eva.start();

Watching states and performing API calls

// watch example. Each item can have multiple watchers, masks '*' are possible.

$eva.watch('unit:tests/unit1', function(state) {
      document.getElementById('u').innerHTML = state.status?'ON':'OFF';
    });

// action example
document.getElementById('u').addEventListener('click', function() {
  $eva.call('action_toggle', 'unit:tests/unit1', { w: 30 })
    then(function(data) {
      console.log('action sent to server, uuid: ' + data.uuid)
      // watch action result
      $eva.watch_action(data.uuid, function(action) {
        if (action.uuid) {
            if (action.is_finished) {
                console.log('action is finished, status: ' + action.status);
            }
        } else {
            console.log('server error');
        }
      });
    }).catch(function(err) {
      console.log('action failed, code: ' + err.code + ', ' + err.message);
    });

Any EVA ICS API method can be called. Methods are called with JSON RPC.

Function call returns Promise object, on success = API call result, on error = object with props:

  • code error code (equal to EVA ICS API client error codes)
  • message error message
  • data full server response

Calling API methods

All API methods are called with call function:

    $eva.call('action', 'unit:tests/lamp1', { s: 1 })
    // or 
    $eva.call('action', { i: 'unit:tests/lamp1', s: 1 })

If first parameter is a string, it's automatically set to "i" argument of API request.

Setting intervals

Intervals are set by interval method, e.g. $eva.interval("reload", 5), value means seconds. Available intervals:

  • action_watch action result watcher interval
  • ajax_reload reload item states when working in AJAX mode
  • ajax_log_reload reload server log records when working in AJAX mode
  • heartbeat server heartbeat interval
  • reload force reload items when working in web socket mode.
  • restart interval between automatic restart attempts.

Handling events

Event handlers are set by on(event, func) and fired on:

  • login.success successful login
  • login.failed login failure
  • ws.event WebSocket event. If handler return false, event is skipped by framework.
  • server.reload server asked clients to reload UI
  • server.restart server is being restarting
  • heartbeat.success successful heartbeat
  • heartbeat.error heartbeat error (default: $eva.restart)
  • log.record new log record to toss
  • log.postprocess log processing is finished (e.g. scroll viewer down)

Each event can have only one handler. Methods call and stop return Promise objects.

Class variables

Class variables are get and set directly, e.g. $eva.login = "operator";

API and Authentication

Authentication variables should set before start() method is called - either login/password or apikey. If there is auth cookie set, API token variable is filled by framework automatically.

  • login user login
  • password user password
  • apikey API key
  • api_uri API URI (don't need to be set if working in web browser)
  • set_auth_cookies if true (default), auth cookie is used to store API token.

Item processing, special

  • debug if true, Framework enters debug mode and everything's logged to console.

  • global_cvars if true (default), all server cvars are set as globals.

  • log.records set max. log records to retrieve from the server.

  • state_updates Possible values:

    • true (default) - get states of all items API key has access to
    • {'p': [types], 'g': [groups]} - subscribe to specified types and groups
    • false - disable state updates
  • ws_mode use web sockets. Set automatically if WebSocket object is detected, can be set to "false" manually before framework start.

Read-only

  • version Framework version (also available as eva_framework_version in browsers)
  • api_token current API token
  • authorized_user current authorized user
  • logged_in boolean, set to true when user is logged in
  • ws Framework web socket object
  • log.level current log level of records to retrieve from the server
  • log_level_nwmes dictionary of log level names (code: name)
  • in_evaHI true if framework runs in evaHI-based web client
  • server_info contains actual server info (output of API test method)
  • tsdiff time difference between client and server

Framework functions

  • start() start Framework and log in

  • restart() restart Framework (default handler for heartbeat error)

  • stop(keep_auth stop Framework. If keep_auth is set to true, logout API method is not called.

  • erase_token_cookies() should be called when login window is displayed to make sure auth cookies are cleared.

  • log_start(log_level) start processing of server logs

  • log_level(log_level) change log level of records read from the server

  • status(oid), value(oid), state(oid) get item state by oid

  • expires_in get lvar expiration time in seconds

  • unwatch(oid, func) stop watching item. If item oid or function is not specified, all watching functions are removed for a single oid (mask) or for all

Server custom variables

All defined CVARs are set as globals after successful log in. CVARs can be also read with method

var myCVAR = $eva.cvar('myCVAR');

QR code for evaHI-based apps

Method hiQR generates QR code for evaHI-compatible apps (e.g. for EVA ICS Control Center mobile app for Android). Current framework session must be authorized using user login. If $eva.password is defined, QR code also contain password value.

Parameters:

  • ctx html element or id to generate QR code in
  • params object with additional parameters:
    • size - QR code size in px (default: 200px)
    • url - override UI url (default: document.location)
    • user - override user (default: authorized_user)
    • password - override (or exclude) password

Example:

  $eva.hiQR('evaccqr', {password: null});

Multi-page interfaces, external authentication

Primary page

If multi-page navigation contains links back to the main page, it should perform a single authentication attempt to re-use existing token:

    var first_time_login = true;

    $eva.on('login.failed', function(err) {
      if (err.code == 2) {
        // show login window
        if (first_time_login) {
          first_time_login = false;
        } else {
          // display err.message
        }
      } else {
        // handle server error
      }
    });

The same method is used when client can authenticate itself with basic authentication on front-end sever or uses :doc:EVA ICS Smartphone application</evahi>.

Secondary pages

By default, the interface should be programmed in a single HTML/J2 document ui/index.html or ui/index.j2, however sometimes it's useful to split parts of the interface to different html page files.

Each HTML document should initialize/login SFA framework to access its functions. However if eva_sfa_set_auth_cookies is set to true, the secondary page can log in user with the existing token:

    $eva.on('login.failed', function(err) {
        // token is invalid or expired, redirect user to main page
        document.location = '/ui/';
    }

Authentication with front-end server

If you have front-end server installed before UI and it handles HTTP basic authentication, you can leave $eva.login and $eva.password variables empty and let framework log in without them.

In this case authorization data will be parsed by SFA server from Authorization HTTP header (front-end server should pass it as-is to back-end SFA).

You can’t perform that action at this time.