Bus UDP bridge

The service provides UDP bridges between EVA ICS IPC bus and 3rd-party applications.

The payload format can be chosen between JSON (default) and MessagePack.

Outgoing payload

Bus events are sent via UDP packets as-is (see EAPI Core events) with an additional “oid” field.

Incoming payload

3rd-party applications can execute any bus methods via RPC payload which has the following fields:

  • method method to be executed

  • params method parameters, optional

  • target target service, optional (the default is eva.core)

E.g. the following payload executes unit toggle action via the node core EAPI RPC:

{
    "method": "action.toggle",
    "params": {
        "i": "unit:tests/fan"
        }
}

Installing/updating

Bus UDP bridge is not included into EVA ICS distribution. To install/update it, either edit “eva/config/python-venv” registry key, specify the desired version in “extra” section (e.g. eva4-bridge-udp>=0.0.1) and rebuild the Python virtual environment (/opt/eva4/sbin/venvmgr build). Or execute:

/opt/eva4/sbin/venvmgr add eva4-bridge-udp
# or
/opt/eva4/sbin/venvmgr add eva4-bridge-udp==N # where N = version number

The latest eva-shell version number can be obtained from https://pypi.org/project/eva4-bridge-udp/

Setup

Use the template EVA_DIR/share/svc-tpl/svc-tpl-bridge-udp.yml:

# UDP bridge service
#
# Requires https://pypi.org/project/eva4-bridge-udp/ Python module installed
command: venv/bin/eva4-svc-bridge-udp
bus:
  path: var/bus.ipc
config:
  # OIDs to subscribe (both local and remotes are subscribed)
  oids:
  - "#"
  # target to send UDP events to, optional
  target: 10.20.0.5:9999
  # incoming listener, optional
  listen: 10.20.0.1:9999
  # format: json or msgpack, the default is json
  #format: json
  # ignore bus events
  #ignore_events: true
  # manual data collection interval
  #interval: 1
user: nobody
workers: 1

Create the service using eva-shell:

eva svc create eva.bridge.udp1 /opt/eva4/share/svc-tpl/svc-tpl-bridge-udp.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.