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;
  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

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",
      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)

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.