Script runner controller

The script-runner controller is used to update item states and execute actions using external shell scripts or programs.

External scripts are useful for rapid-draft integration of an equipment or if the equipment does not require high-speed actions/updates.

Commons

When executed, a script has the following environment variables set:

EVA_BUS_PATH path to the bus socket
EVA_DIR EVA ICS directory
EVA_ITEM_OID item OID (e.g. sensor:plant1/tests/env)
EVA_ITEM_FULL_ID item full id (e.g. plant1/test/env)
EVA_ITEM_GROUP item group (e.g. plant1/test)
EVA_ITEM_ID item short id (e.g. env)
EVA_ITEM_PARENT_GROUP the nearest parent group (e.g. test)
EVA_ITEM_TYPE item type (e.g. sensor)

Update scripts

The update scripts must print current state for item(s), a single one or multiple, in order as configured, separated by space:

<STATUS> [VALUE]

The status field is always i16, the value is optional, e.g.:

1 12.95
1 2.77

If state values exist, they are automatically converted to numerics if possible.

The update is considered as failed if the script exits with a non-zero code.

Action scripts

Action scripts are executed with the following parameters:

path/to/script <STATUS> [VALUE]

where status/value is the desired action state.

The action is considered as failed if the script exits with a non-zero code.

Sometimes to perform an action, the current unit state is required. There are no environment variables in the service to avoid unnecessary action-preparation bus calls. In case if the state is required, it can be obtained manually via a command-line bus call:

"${EVA_DIR}/sbin/bus" -s "$EVA_BUS_PATH" \
    rpc call eva.core item.state "i=$EVA_ITEM_OID" | jq -r ".[0]"

It is recommended to store the state in a variable and use jq later to parse required fields.

Setup

Use the template EVA_DIR/share/svc-tpl/svc-tpl-controller-sr.yml:

# Scrpt-runner controller service
command: svc/eva-controller-sr
bus:
  path: var/bus.ipc
config:
  update:
    - command: xc/sr/temp_update.sh
      oid: sensor:tests/temp # single OID or list
      interval: 2 # update interval, required
      timeout: 10 # override the default timeout, optional
    - command: xc/sr/update_multiple.sh
      oid:
        - sensor:tests/s1
        - sensor:tests/s2
      interval: 5
  action_map:
    unit:tests/u1:
      command: xc/sr/u1_action.sh
      timeout: 10
      # trigger update after actions
      update_after: true
  # event queue size
  queue_size: 2048
  # action queue size, per unit
  action_queue_size: 32
user: eva

Create the service using eva-shell:

eva svc create eva.controller.sr1 /opt/eva4/share/svc-tpl/svc-tpl-controller-sr.yml

or using the bus CLI client:

cd /opt/eva4
cat DEPLOY.yml | ./bin/yml2mp | \
    ./sbin/bus ./var/bus.ipc rpc call eva.core svc.deploy -

(see eva.core::svc.deploy for more info)

EAPI methods

See EAPI commons for the common information about the bus, types, errors and RPC calls.

action

Description	Executes a mapped unit action
Parameters	See Unit actions
Returns	See Unit actions

kill

Description	Attempts to terinate/cancel all actions for a unit
Parameters	See Unit actions
Returns	See Unit actions

terminate

Description	Attempts to terminate/cancel a unit action
Parameters	See Unit actions
Returns	See Unit actions

update

Description	Triggers item update
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	Item OID	yes