SCADA Final Aggregator
SCADA Final Aggregator (SFA) is a subsystem usually installed directly in the host wherein the user interface or third-party applications are installed.
It aggregates all the control and monitoring items, logic macros and decision rules from all connected UC and LM PLC controllers into one place. As a result, the final interface or application doesn’t need to know on which controller the item is present, it does all the function calls directly to SFA. Ids of the items should be always specified in oid form (type:group/id) and be unique in the whole installation.
SFA is set up and controlled with eva sfa console application and SFA API. The API doesn’t have a user interface by default, it’s developed specifically for certain installation certain installation using SFA Templates (server-side part) and EVA ICS JS Framework (client-side part).
All changes of item status, actions, and logs are sent to the notification system. In addition, SFA can function as the notification aggregator e. g. by transferring MQTT messages to other application via HTTP or redirecting them to other MQTT servers. SFA usually has several or all available controllers connected. At least one MQTT server should be installed in the setup to let it work in real time. Since SFA is a part of EVA platform, its operating principles, settings, and configuration files generally match the other components.
config/sfa/main registry key
config/sfa/main registry key contains the controller configuration.
server:
# system poll delay
polldelay: 0.01
# pid file
pid-file: var/sfa.pid
# log file
log-file: log/sfa.log
# custom primary log format
#log-format: '{ "loggerName":"%(name)s", "timestamp":"%(asctime)s", "pathName":"%(pathname)s", "logRecordCreationTime":"%(created)f", "functionName":"%(funcName)s", "levelNo":"%(levelno)s", "lineNo":"%(lineno)d", "time":"%(msecs)d", "levelName":"%(levelname)s", "message":"%(message)s" }'
# logging to local syslog
#syslog: true
# logging to non-standard (/dev/log) local syslog socket
#syslog: /var/run/syslog
# logging to remote syslog
#syslog: hostname:514
# custom syslog format
#syslog-format: 'EVA: { "loggerName":"%(name)s", "timestamp":"%(asctime)s", "pathName":"%(pathname)s", "logRecordCreationTime":"%(created)f", "functionName":"%(funcName)s", "levelNo":"%(levelno)s", "lineNo":"%(lineno)d", "time":"%(msecs)d", "levelName":"%(levelname)s", "message":"%(message)s" }'
# db updates - instant, manual or on-exit
db-update: instant
db-file: runtime/db/sfa.db
# use MySQL instead of SQLite
#db: mysql+pymysql://user:password@localhost/dbname
# user db file, default = db-file
# one user db may be used by multiple controllers simultaneously
#userdb-file: runtime/db/users.db
# use MySQL instead of SQLite
#userdb: mysql+pymysql://user:password@localhost/dbname
# launch external script/program when user is created/got new
# password/destroyed. additional arguments:
# 1) create | set_password | destroy
# 2) user
# 3) password (for create and set_password operations)
#user-hook: "/opt/eva/xbin/htpasswd.sh /opt/eva/etc/htpasswd"
# keep action history in seconds
keep-action-history: 86400
# action cleaner interval, in seconds
action-cleaner-interval: 60
# keep memory log in seconds
keep-logmem: 86400
# minimal log level
#logging-level: warning
# keep extended API call log in user db in seconds (0 = disable logging)
#keep-api-log: 0
# notify states on start
notify-on-start: true
# debug mode
debug: false
# log code tracebacks
#show-traceback: true
# create crash dump on critical errors
dump-on-critical: true
# stop server on critical errors (will be restarted via safe-run)
# always - stop on all critical errors
# core - core errors only (ignore driver critical errors)
# false - don't stop
stop-on-critical: always
# default timeout
timeout: 5
# default suicide timeout (kill -KILL process on shutdown)
#suicide-timeout: 30
# primary thread pool, min workers. comment to pre-spawn all workers
#pool-min-size: 0
# primary thread pool, max workers. comment to use automatic value (nCPUs * 5)
#pool-max-size: 100
# reactor thread pool size (used by Modbus slave and some utility workers)
#reactor-thread-pool: 15
#
# exec commands before/after config/db save,
# e.g. mount -o remount,rw / (then back to ro)
#
#exec-before-save: "mount -o remount,rw /"
#
#exec-after-save: "mount -o remount,ro /"
#
# default mqtt notifier for updates for new items
#mqtt-update-default: "eva_1:2"
# auto-save created items
auto-save: true
#lurp:
# LURP replication
# listen: 127.0.0.1:8921
# buffer: 32768
#msad:
# user authentication via MS Active Directory
#host: ad.yourdomain.com
#domain: yourdomain.com
#key-prefix: ""
#ou: EVA
#ca: /path/to/ca-file.crt
# cache credentials for the specified time (seconds)
# default: 86400 (1 day), 0 to disable caching
#cache-time: 86400
upnp:
# allow UPnP discovery of this controller
listen: 0.0.0.0
# discover controllers via UPnP on all interfaces, or list
discover-on: all
sysapi:
# enable remote file management functions
file-management: true
# allow entering setup mode
setup-mode: true
webapi:
# web api listen on IP/port
listen: 0.0.0.0:8828
#ssl-listen: 0.0.0.0:8829
#ssl-module: builtin # or pyopenssl
#ssl-cert: test.crt
#ssl-key: test.key
#ssl-chain: test.pam
# session timeout, set to non-zero to enable API session tokens
session-timeout: 3600
# session tokens will expire even if active requests are received
#session-no-prolong: true
# server thread pool
#thread-pool: 15
# disable UC EI
#ei-enabled: false
# use frontend X-Real-IP header to get client real IP address
#x-real-ip: true
# override real ip header name
#real-ip-header: X-IP
cloud:
# enable/disable cloud manager
cloud-manager: false
# default API key ID
default-key: default
# discover controllers as static
#discover-as-static: true
Custom variables
Custom variables can be changed while the server is running via Common methods as well as eva sfa cvar_get and cvar_set commands.
All SFA custom variables are directly available in SFA Templates and EVA ICS JS Framework after login with any valid user or API key.
Variables can be changed while the server is running via Common methods as well as eva sfa cvar get and cvar set commands.
Connecting UC and LM PLC controllers
SFA works only with the items known to the controller. Prior to connecting UC and LM PLC remote controllers, it is necessary to connect SFA to MQTT server (via its notification system), to which other controllers will send the events. SFA reads the list of items, macros, rules and the initial item status from the connected controllers; further status updates are performed via MQTT.
For timers to be displayed correctly in the user interface, it is important to maximally synchronize the system time between LM PLC and SFA, if LM PLC controllers are set up on the remote servers.
To connect the controllers you should use eva sfa (sfa-cmd) console command or SFA API append_controller function.
When connecting, it is necessary to indicate minimum URI of the connected controller and API KEY functioning either as a master key or the key with access to certain items. If Logic Manager and UC keys are the same, the key can be set as $key (\$key in the command line). In this case, LM will use the local key of its own configuration.
eva sfa append_controller -u http://localhost:8812 -a secretkey -y
eva sfa append_controller -u http://localhost:8817 -a secretkey -y
You may specify a controller type with -g argument (-g uc or -g lm). If the group is not specified, SFA tries to automatically detect the remote controller type.
Configurations of the connected controllers are stored in the folder runtime/sfa_remote_uc.d/ for UC and runtime/sfa_remote_lm.d/ for LM PLC.
SFA automatically loads the connected controller data (its id) and saves the configuration to runtime/sfa_remote_<type>.d/<ID>.json.
Items from remote controllers are loaded at the SFA start and then refreshed with reload_interval frequency set individually for each connected controller. If SFA fails to get the item list during loading, it will use the existing one.
To control the list of the received items you can use eva sfa or SFA API function list_remote:
eva sfa remote -p unit
eva sfa remote -p sensor
efa sfa remote -p lvar
The available logic macros are listed by the command
eva sfa macro list
Note
Macros from system group and its subgroups are not loaded to SFA
All connected controllers have the following properties that can be changed while SFA is running:
description optional description of the controller
key API key used to access the connected controller
mqtt_update MQTT notifier through which items update their status
reload_interval interval (seconds) to reload the item list from the server, 0 - load the list only at the start
ssl_verify either verify or not the SSL certificate validity when working through https://. May be True (verify) or False (not verify) The certificate is verified by default.
timeout request timeout (seconds)
uri API URI of the connected controller (proto://host:port, without /uc-api/ or /lm-api/)
Parameters are displayed with eva sfa command or SCADA Final Aggregator list_controller_props function, modified with set_controller_prop. Function list_controllers displays the list of all connected controllers.
To remove the connected controller use remove_controller function.
When managing the connected controllers, ID should be always provided in the full format: controller_type/ID (i.e. uc/controller1).
Interface
SFA interface is always specifically designed for a certain installation using SFA Templates, EVA ICS JS Framework and SFA PVT. Interface files are stored in ui folder, interface is available at http(s)://<IP_address_SFA:Port>/ (redirects to /ui/) or http(s)://<IP_address_SFA:Port>/ui/.
Startup and shutdown
To manage SFA controller server, use:
eva sfa server start start SFA server
eva sfa server stop stop SFA server
eva sfa server restart restart SFA server
eva sfa server reload restart controller only (without watchdogs)
The controller startup/shutdown is also performed by ./sbin/eva-control which is configured during the system setup.