Drivers

Universal Controller uses 2 ways for controlling and monitoring items:
item scripts and drivers. Drivers are the most advanced
way, they are faster, contain all process logic and can be used to work with
devices on a single bus, providing locking/unlocking mechanisms.

Code of driver is executed directly inside the controller core and unlike
script can’t be terminated, unless it gets termination signal and decides to
stop. If driver process causes timeout and there is no way to stop it,
controller raises a critical exception and may terminate itself.

You should always use only reliable and tested drivers, otherwise your system
may become unstable.

Structure

Each driver contains 2 modules: LPI (logical to physical interface) and PHI
(physical interface). To load new driver into controller, follow the steps:

List the available PHI mods:

eva uc phi mods

Get PHI module information:

eva uc phi modinfo <phi_module>

If the desired PHI is not listed, download it and put to xc/drivers/phi
folder. Official PHI modules are available at https://www.eva-ics.com/phi.
You may either download the module manually or use

eva uc phi download <phi_module_uri>

command. Note that UC host doesn’t need to have a direct connection to the host
you download PHI from, module is downloaded first to the host where eva CLI
(or eva uc) is started, verified and then automatically uploaded to the
controller.

Execute the command to list PHI configuration variables:

eva uc phi modhelp <phi_module> cfg

This will display the configuration variables, used when PHI is loaded (port
numbers, default values etc.). Variables marked required=True should be
always defined otherwise controller will fail to load PHI.

Param -y is used to ask the controller to save driver configuration right
after PHI is loaded.

After the successful load, PHI will automatically create the most suitable
driver for itself, called <phi_id>.default. This usually provides basic
driver logic and doesn’t mean the driver is suitable for your task. You may
replace it’s LPI module or define a different driver with another LPI.

Param -y is used to ask the controller to save item configuration right after
driver is assigned.

Param -c is used to set driver configuration for the specified item: set
port, logic etc.

Advanced usage: EVA item can have different drivers or scripts
for actions and updates. To assign different drivers, modify item properties
action_exec, update_exec, action_driver_config and
update_driver_config (e.g. with eva uc config props). Driver is assigned
to the property with |driver_id value, e.g. |v1.default.

Note

All custom-defined user variables are always passed to
driver function calls, which allows to set some device-specific or
logic-specific options as global or for the particular item group.

How the driver handles action commands

Note that params started with _ are passed to PHI calls directly (without
_ prefix), this allows specifying different hosts, bus addresses (if PHI is
developed as “universal”) without a need to load different drivers for each
item.

How the driver handles update commands

Use commands eva uc phi unload and eva uc phi unlink to unload and unlink
unnecessary PHI modules, but note that driver and PHI can’t be unloaded while
they’re assigned to items. You must first assign a different driver to the item
or use eva uc driver unassign command.

You can load PHIs/drivers with the same IDs even if they are already present in
the system without unloading them first. In this case, new
modules/configuration replace the old ones.

Logical to physical interfaces (LPI)

LPI module handles the whole driver logic and doesn’t contain any code,
specific for the equipment. All it needs is to process the logic and call the
assigned PHI.

When the controller loads new PHI, it creates a driver called <phi_id>.default,
assigning LPI to provide basic functionality, but you may want to replace it or
use different logic for different items.

To list available LPI mods, use the command:

eva uc lpi mods

To get module information, use the command:

eva uc lpi modinfo <lpi_module>

Currently we don’t provide any additional LPI modules or SDK, all available
mods are included in EVA ICS distribution.

ssp LPI

Similar to sensor LPI, but doesn’t contain any options at all. Used when
PHI can work only with one physical equipment (e.g. sensor with TCP/IP API) and
all equipment options are already set in PHI.

esensor LPI

Sensor monitoring with advanced functions. Can monitor physical sensor groups
returning average, maximum or minimum value. Can ignore sensor values if they
seem to be invalid in case one or several sensor in a group fail (while there
are enough working sensors in a group).

Configuration options (set with eva uc driver load):

skip_err If True, failed physical sensor in a group will be skipped,
otherwise EVA sensor item gets error value.

gpf Group port function, get values from the sensors in a group, then
return:

avg average value

max maximum value

min minimum value

first first available value from any working physical sensor

max_diff maximum value difference until the sensor in a group is marked
as failed and its value is ignored. E.g.: set this option 10 and let it
poll the temperature sensors group. All sensors with temperature difference
10 degrees or more from the average are ignored.

Update options (set with eva uc driver assign):

port driver port or ports (array). If you use multiple ports (group),
they should be separated with pipes (|) for the items. Group separation
for EVA multiupdate items should be made with double pipes (||)

any configuration option (optional). E.g. if gpf=avg is defined, it
overwrites default LPI behavior for the specified item.

multistep LPI

Module used for such common tasks as door or window opening. To use this module
you must connect your equipment to 2 relay ports: one will give power to
motors, the second will set the direction.

Configuration options (set with eva uc driver load):

bose (break on state error). The module requires to know the current door
or window position is. If you set this option to True and the current item
status is error, the action will be not executed. Otherwise LPI will pass and
consider the item status is 0.

Action options (set with eva uc driver assign):

port contains one or several (separated with |) relay ports used to
power a motor.

dport contains one or several (separated with |) relay ports used to
set a direction.

steps list of float numbers, contains time (in seconds) of power access
period to the motor to reach the next step. E.g. you have a door with 3
positions: closed, half-open and completely open. steps option will
contain 2 numbers (e.g. 20|25) which tells LPI the door state from 0 to
1 is changed by running motor for 20 seconds, the state from 1 to 2
is changed by running motor for 25 seconds, so LPI can automatically
calculate the full opening/closing cycle is 45 seconds.

warmup float number (seconds). LPI will add this value to the time for
running the motor if the state is neither fully open nor fully closed, to
let it “warm up” before doing actual work.

tuning float number (seconds). LPI will add this value to the time, if
action is open full or close full to make sure the door is fully
open/closed.

ts (to-start) number which indicates the following: e.g. you have a door
with status from 0 (fully closed) to 5 (fully open) and defined the
middle states with steps. But when calling action “set this door to 2”
you can’t be sure the door position is equal when setting it from fully
open and fully closed. But if you set e.g. ts=2 and the current status
is greater than 2, it will tell LPi firstly to completely close the door
(go to status=0) and then go to status=2.

te (to-end) same as ts but in an opposite way: set the status number,
starting from which the door will be fully open first, then go to the desired
status.

Note

LPI will completely refuse to run the action if it calculates that therese
is not enough time to complete it. Set item action_timeout to the
proper value.

Update options:

The module doesn’t provide any state update functionality. If you want to sync
door/window item states with real, use separate reed switch sensor.

Loading driver with the chosen LPI

Firstly, you can list available LPIs with the command:

eva uc lpi mods

Consider the desired PHI is already loaded. To load the driver and combine
PHI+LPI, use the command:

We’ve already described how to get and load PHIs, here is some
additional important information.

Universal PHIs

If the word “universal” is listed in PHI features, it means the module can be
loaded once and provide interface for all supported equipment. E.g. let’s take
a look on sr201 PHI module which provides support for SR-201 compatible
relays:

All of cfg, get and set have an option host which should be
defined ether in PHI configutation (eva uc phi load with host config option
or in item driver configuration (eva uc driver assign with _host config
option). Setting different host option value in item driver configuration
lets one sr201 PHI manage all available SR-201 relays.

Physical events

If the word “events” is listed in PHI features, it means the module can handle
hardware events e.g. react to the alarm sensors or update item state when an
external event is received.

How the driver handles physical events

In practice, it means PHI provides data, obtained from the hardware, to
controller and asks it to update all items using drivers which contain PHI
module which have an event.

When doing update, drivers LPI modules don’t ask PHI to get hardware data
working only with data already provided by the hardware.

Drivers and multi updates

If the word “aao_get” is listed in PHI features, it means you don’t need to
create multiupdates in Universal Controller to update several items at once. “aao_get”
(all-at-once-get) means PHI can obtain all hardware data itself and then ask
the controller to update all items using drivers which contain PHI equally to
updating on physical events.

How to use this feature: All PHIs with “aao_get” feature also have
configuration param named update which means how frequently (in seconds) PHI
should collect data from the equipment and initiate item updates. update
value should be defined in PHI load config and be greater than zero.

Example:

eva uc phi load relay2 sr201 -c host=192.168.20.2,update=5 -y

As soon as the driver is assigned to item (eva uc driver assign), it starts
getting state updates every 5 seconds.

Testing PHIs and additional PHI commands

As soon as PHI is loaded, you can test how it works. All PHI modules respond to
the command:

eva uc phi test <phi_id> self

which returns result “OK” or “FAILED”.

PHI can provide additional testing; to get a list of testing commands, execute:

eva uc phi test <phi_id> help

Some PHIs can provide additional commands to set up or control the hardware
equipment. To get a list of these commands, execute: