Packages

Custom extensions and other data can be packed into packages.

Package format

EVA ICS packages have very simple format:

  • The package should be tar or tgz archive, which is extracted to EVA_DIR as-is

  • The package MUST contain the file, called setup.py

  • The package SHOULD have the suffix .evapkg

Setting up packages

Packages can be installed either via install_pkg API method of any controller or with IaC deployment (in this case, only Universal Controller or Logic Manager packages can be installed, or the controller should have corresponding writing permissions to install e.g. UI files).

Setup file format

The Setup file should be called “setup.py” and is launched as EVA ICS corescript (so it has the access to all core script methods). The script is launched with the event:

event.type == CS_EVENT_PKG_INSTALL

The variable event.data contains package setup params, specified in the API call option “o”.

The script also has the special method extract_package. When called, this method extracts contents of the uploaded package to EVA ICS directory.

Note

Setup script has no access to the package files, except calling extraction method. The package is uploaded to controller’s memory and there is no temporary file written.

Here is a very simple example of the package setup script:

if event.type == CS_EVENT_PKG_INSTALL:
    logger.warning(f'installing package with options: {event.data}')
    extract_package()

The package setup script SHOULD check event type, as it can be launched with other core script events later (functionality is reserved for the further EVA ICS versions).

Keeping setup core script after install

Sometimes it is useful to keep setup core script code after the package installation is completed. To do that, the function “keep_me()” can be used:

# ... perform setup tasks
keep_me()

When called, the new core script is created from the setup corescript code, for the controller the package is installed on. This can be useful if the package requires performing additional tasks, e.g. starts / stops some service at the controller startup / shutdown.

Installing additional Python modules

The function “pip_install” allows installing additional Python modules, calling “pip install” command from EVA ICS venv. The modules are also automatically added to the node venv configuration.

# ... perform setup tasks
pip_install('flask')

Manipulating with configuration files

The setup core script automatically has configuration helpers in globals. These helpers are already in globals and should not be imported manually.

class ConfigFile(fname, init_if_missing=False, backup=True)

A helper to manage .ini files

Example

with ConfigFile(‘file.ini’) as cf:

cf.set(‘section’, ‘field1’, ‘value1’)

add_section(section, values)

Add section with dict of values

append(section, name, value)

Append value to array field (in .ini configs, arrays are string fields with values, separated with commas)

delete(section, name)

Delete field from section

get_section(section)

Get dict of section values

is_changed()

Returns True, if configuration file was changed and will be saved after the statement exit

remove(section, name, value)

Remove value from array field

remove_section(section)

Remove section

replace_section(section, values)

Replace section with dict of values

set(section, name, value)

Set section field value

class ShellConfigFile(fname, init_if_missing=False, backup=True)

A helper to manage shell scripts configuration files

Example

with ShellConfigFile(‘eva_config’) as cf:

cf.set(‘KEYNAME’, 0)

append(name, value)

Append value to array field (in shell configs, arrays are string fields with values, separated with spaces)

delete(name)

Delete field

get(name, default=<class 'KeyError'>)

Get field value

is_changed()

Returns True, if configuration file was changed and will be saved after the statement exit

remove(name, value)

Remove value from array field

set(name, value)

Set field to value