Script runner controller

Contents

• Script runner controller

  • Commons

  • Update scripts

  • Action scripts

    • Current unit states

  • Setup

  • EAPI methods

    • action

    • kill

    • terminate

    • update

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

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

Current unit states

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
  # update pipes launch a process and process its output line by line
  # STDOUT goes to process lmacro, while STDERR is logged as errors
  # the process is restarted automatically if it exits
  update_pipe:
      # the command path MUST be absolute or the command must be in PATH. the
      # command may contain arguments
    - command: some-command --some-args
      # the process lmacro receives a keyword argument "line" which contains
      # the line read from the process STDOUT. If the "line" contains null, it
      # means the process exited and the lmacro should mark related items as
      # failed
      process: lmacro:process/pipe1
  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