Low-level hooks

useEvaStateUpdates

React hook, which automatically switches EVA ICS WebEngine state updates.

It is highly recommended to set WebEngine state updates to false by default, especially for large setups, (see Configuring) and subscribe only to states of items which are currently displayed.

Parameters

interface EvaStateUpdatesParams {
  engine?: Eva;
  state_updates: Array<string> | boolean;
  // do not keep WebEngine states for non-subscribed
  clear_existing?: boolean;
  // return previous subscription when the component is unmounted
  // if not set to true, the hook unsubscribes the engine from all events
  keep?: boolean;
  // append subscription to the existing one
  append?: boolean;
}

Usage example

import {
    useEvaStateUpdates,
    useEvaState,
    EvaSubscriptionState, // optional, used by the following example
    ItemValue // optional, used by this example
} from "@eva-ics/webengine-react";

const PageSensors = ({plant}:{plant: string}) => {
  const sub_state = useEvaStateUpdates({
    state_updates: [`sensor:${plant}/#`],
  }, [plant]);

  return (
      <div>Sensors dashboard ({plant})</div>
      <div>Temperature:
          <ItemValue oid={`sensor:${plant}/temp`} digits="2" units="C" />
      </div>
      <div>Humidity:
          <ItemValue oid={`sensor:${plant}/hum`} digits="2" units="%" />
      </div>
  );
}

The current subscription operation state can be optionally parsed and used to e.g. display a loading progress message:

switch (sub_state) {
  case EvaSubscriptionState.Active: // the engine subscription is switched
    return <div>Dashboard</div>;
  case EvaSubscriptionState.Working: // switching in progress
    return <div>Loading...</div>;
  case EvaSubscriptionState.Failed: // switching failed
    return <div>Failed!</div>;
}

useEvaState

React hook, which contains state of EVA ICS item. The state is automatically updated in real time.

This is the basic hook to get item states, which is used in the majority of UI components.

Parameters

interface EvaStateParams {
  oid: string;
  engine?: Eva;
}

Usage example

import { useEvaState } from "@eva-ics/webengine-react";

const MyComponent = () => {
  const state = useEvaState({ oid: "sensor:env/temp" });

  return <span>{state?.value}</span>;
}

useEvaStateHistory

React hook, which contains historical state of EVA ICS item. The state is automatically updated with the specified interval.

The hook is used in LineChart component. It also can be used to output various analytics tables and custom charts.

Parameters

interface EvaStateHistoryParams {
  oid: string | Array<string>;
  timeframe: string | Array<string>;
  update?: number;
  prop?: StateProp;
  fill?: string;
  args?: any;
  update_uninit?: number;
  engine?: Eva;
}

  • timeframe contains a single or multiple time frames (see item.state_history for time frame format). The time frame can be specified as START:END, e.g. to output the data for the previous hour: 2H:1H.

  • update update interval in seconds (default: 1 sec)

  • fill filling interval (see item.state_history)

  • args extra API call arguments

  • update_uninit (seconds) when used standalone with no web-engine HMIApp component and no login.success callback, refresh login status more frequently than update interval set. Use in case of problems when the first hook iteration is skipped.

Note

Time convention used in EVA ICS time-frames to fill data:

  • S for seconds (e.g. 5S for 5 seconds)

  • T for minutes

  • H for hours

  • D for days

  • W for weeks

  • A to get automatic number of records (e.g. 5A for 5 exactly records)

Time convention used in EVA ICS to specify start/end of a timeframe:

  • If there are dedicated parameters for start/end, they are filled separately

  • If there is a single parameter only, it is filled either as START:END or as START only (END is automatically set to the current time)

where values must be:

  • UNIX timestamps only (if a parameter is strictly specified as a number)

  • Date in human-readable format (RFC3339 recommended)

  • Using the same notation as for filling. E.g. setting start=30T sets time-frame start to 30 minutes before now.

START value is always mandatory. If END value is required to be set to the current time, it can be omitted.

Output

interface StateHistoryData {
  data: any;
  error?: EvaError;
}

Usage example

import { useEvaStateHistory } from "@eva-ics/webengine-react";

const MyComponent = () => {
  const state = useEvaStateHistory({
      oid: "sensor:env/temp",
      timeframe: "1D",
      fill: "30A", // get exactly 30 records
      update: 1
  });

  // ...

}

The state.data variable contains item.state_history API call result, which is updated with the specified interval.

In case of API call error, state.error is filled with error information.

useEvaAPICall

React hook, which contains HMI service API call result. The result payload is automatically updated with the specified interval.

Parameters

interface EvaAPICallParams {
  method: string;
  params?: object;
  update?: number;
  engine?: Eva;
}

  • update update interval in seconds (default: 1 sec)

  • update_uninit (seconds) when used standalone with no web-engine HMIApp component and no login.success callback, refresh login status more frequently than update interval set. Use in case of problems when the first hook iteration is skipped.

Output

interface APICallData {
  data: any;
  error?: EvaError;
}

Usage example

import { useEvaAPICall } from "@eva-ics/webengine-react";

const MyComponent = () => {
  const result = useEvaAPICall({
    method: "bus::sim.modbus.sensor1::get",
    update: 1
  });

  let value = result.data?.value;
  return <span>{value}</span>;
}

The result.data variable contains API call result, which is updated with the specified interval.

In case of API call error, result.error is filled with error information.