Data generator

Contents

The data generator service allows to generate both real-time and archive data for both sensor/lvar states and EAPI commons RPC calls to other services.

Generators are useful for modelling and testing purposes, both for HMI application, logic and AI/statistical analysis.

There is no service instance set up by default and it need to be configured manually.

Usage

When deployed, generators get data from sources and put them either to DCS Items values or to RPC targets.

A single generator source can send source values to multiple targets.

Item targets

Must be specified as OIDs, e.g.

sensor:tests/voltage

RPC targets

Must be specified as SVC_ID[::method][@PARAM=VALUE,PARAM=VALUE]

If the service method is omitted, var.get is used
If the parameter name is omitted, i is used
The value always goes to value field of RPC payload

e.g. set TwinCAT variable:

eva.controller.ads1::var.set@MAIN.test1

Sampling

Source sampling means the frequency the source value is applied to targets. The default and the minimal value is “1” (once a second).

Planning

A generator source configuration can be planned using EAPI RPC call to source.plan or with eva-shell:

eva generator source plan wave "formula=sin(x/2)*10+10" --sampling 1 --duration 60 --output line

eva-shell supports the following output formats:

table value table (use eva -J generator source plan for JSON output)
bar console bar chart
line console line chart

Note

If calling via RPC, the payload may contain any source name (e.g. “_”)

Applying

A generator can apply data to targets’ historical states. Use eva generator source apply command or source.apply RPC method.

Note

If calling via RPC, the payload may contain any source name (e.g. “_”)

Warning

When applying, the generator may flood database services. Consider configuring the services to temporary accept large amnounts of data by increasing bus/internal queue/buffer sizes.

Generator sources

Counter

The source provides a counter which is started from min value and resetted at the max one. The counter is increased every second with step value (1 by default).

Sample source payload:

kind: counter
name: s1
params:
  min: 0
  max: 20
  step: 2
sampling: 1
targets:
- sensor:tests/voltage

Random

The source provides a random generator which generates an integer value between min and max.

Sample source payload:

kind: random
name: s1
params:
  min: -10
  max: 10
sampling: 1
targets:
- sensor:tests/voltage

Random float

The source provides a random generator which generates a float value between min and max.

Sample source payload:

kind: random_float
name: s1
params:
  min: -5.0
  max: 5.0
sampling: 1
targets:
- sensor:tests/voltage

Time

The source provides a generator which reads values from a clock and sends them to targets in a specified format.

kind: time
name: t1
params:
  clock: local
  format: timestamp
sampling: 1
 targets:
 - sensor:tests/timestamp

Clocks supported:

local local time (default)
utc UTC time
monotonic system monotonic clock

Formats supported:

timestamp integer timestamp (default)
timestamp_float float timestamp with nanoseconds
timestamp_nanos integer timestamp with nanoseconds
rfc3339 RFC-3339 date string
year the current year
month the current month (integer)
day the current day of the month
hour the current hour
minute the current minute
second the current second

Limitations:

the source does not support plan command
the source does not support apply command
the clock monotonic supports timestamp formats only

UDP float

The source provides a UDP port which accepts raw little-endian encoded IEEE-754 float numbers. This type is useful to accept data from 3rd party software e.g. from MATLAB Simulink default UDP sinks.

Sample source payload:

kind: udp_float
name: s1
params:
  bind: 0.0.0.0:20001
targets:
- sensor:tests/voltage

Limitations:

sampling parameter is ignored
the source does not support plan command
the source does not support apply command

Wave

The source provides a generator which generates a custom wave using the given formula:

Sample source payload:

kind: wave
name: s1
params:
  formula: "sin(x/2)*10+10"
  shift: 0
sampling: 1
targets:
- sensor:tests/voltage

An optional shift parameter allows to shift the wave in time forward or backward.

Functions supported:

sqrt, abs
exp, ln
sin, cos, tan, asin, acos, atan, atan2
sinh, cosh, tanh, asinh, acosh, atanh
floor, ceil, round
signum
max(x, …), min(x, …): maximum and minimumum of 1 or more numbers

Note

The formula must contain at least one function with x argument.

Built-in constants:

pi
e

Setup

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

command: /opt/eva4/svc/eva-svc-generator
bus:
  path: var/bus.ipc
config:
  verbose: false
user: nobody

Create the service using eva-shell:

eva svc create eva.generator.default /opt/eva4/share/svc-tpl/svc-tpl-generator.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.

source.apply

Description	Apply source to archive data
Parameters	required
Returns	Apply job ID

Parameters
Name	Type	Description	Required
source	struct	Source	yes
t_start	String/f64	Starting time/timestamp	yes
t_end	String/f64	Ending time/timestamp (def: now)	no
targets	Vec<String>	target item OIDs	no

Return payload example:

{
    "job_id": "e36c624b-bac0-4a6b-b520-8dc5dedc726d"
}

source.deploy

Description	Deploy sources
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
generator_sources	Vec<struct>	Sources	yes

source.destroy

Description	Destroy a single source
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	Source name	yes

source.get_config

Description	Get configuration of a single source
Parameters	required
Returns	Source configuration

Parameters
Name	Type	Description	Required
i	String	Source name	yes

Return payload example:

{
    "kind": "wave",
    "name": "v1",
    "params": {
        "formula": "sin(x/2)*10+10"
    },
    "sampling": 1,
    "targets": [
        "sensor:tests/voltage"
    ]
}

source.list

Description	List generator sources
Parameters	none
Returns	List of sources (struct)

Return payload example:

[
    {
        "active": true,
        "kind": "wave",
        "name": "v1"
    }
]

source.plan

Description	Plan a source
Parameters	required
Returns	Source output

Parameters
Name	Type	Description	Required
source	struct	Source	yes
duration	f64	planning duration	no
fill	String	Fill (nS/T/H/D/W e.g. 10T for 10-minute)	no

Return payload example:

[
    {
        "t": 0.0,
        "value": 10.0
    },
    {
        "t": 1.0,
        "value": 17.071067811865476
    },
    {
        "t": 2.0,
        "value": 20.0
    },
    {
        "t": 3.0,
        "value": 17.071067811865476
    },
    {
        "t": 4.0,
        "value": 10.000000000000002
    },
    {
        "t": 5.0,
        "value": 2.9289321881345254
    }
]

source.undeploy

Description	Undeploy sources
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
generator_sources	Vec<struct/String>	Sources or a list of source names	yes