Logic manager

Contents

Logic manager is a software programmable logic controller, which allows to cope with typical automation tasks.

Functionality

Rules

A rule is a way to react to item state events, either for a particular item or for an item mask.

If an event matches condition and the previous state was out-of-condition range, the rule executes lmacro handler, a local or remote.

The handler receives additional keyword arguments:

Name	Content
source	Event source (state + OID)

Chillout

If a rule has chill-out time set and an event matches the rule condition, further events are ignored until chill-out time is over.

If a rule receives match-event during the chill-out time, the handler is executed right after the chill-out is over. source argument contains the last event received during the chill-out.

A cycle is a high-performance loop-executor for a lmacro, a local or remote. The service provides cycles up to 1000Hz (interval 0.001 sec = 1ms), nevertheless cycle frequencies are usually limited to lmacro execution time (e.g. Python macros controller has the fastest execution time near 3ms for local actions).

In case of errors, an error-handler lmacro is called if defined, which gets the following args:

Error	Arg 1	Arg 2
Cycle timeout	cycle	timeout
Handler error	lmacro	result error as-is
Handler timeout	lmacro	timeout
Handler exec error	exec	BUS error code (i16)

Cycles can be started automatically or manually, via BUS calls. E.g. to start a cycle with Python Logic Macros, use rpc_call method.

Jobs

A job is a low-performance loop or scheduled executor for a lmacro, a local or remote.

Jobs provide the same functionality as the system cron, except the smallest execution time unit is a second, plus optionally year(s) can be set.

Note

Job schedulers use local time, which may cause certain commands to be repeated/skipped if the system time goes backward/forward, when corrected or during dayling saving switches.

Setup

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

# Logic manager programmable controller
command: svc/eva-controller-lm
bus:
  path: var/bus.ipc
config:
  rules: []
    #- id: rule1
      #oid: sensor:#
      #prop: status # status, value or act (for units)
      # full condition notation, can be shortened as x = -1
      #condition:
        #min: -1
        #max: -1
        #min_eq: true
        #max_eq: true
      #break: false # do not process further rules if mathces
      #chillout_time: 10 # ignore further events, seconds
      #run: lmacro:tests/sensor_down
      #initial: process # process, skip, only
      #block: false # block rule processing until the macro is finished
    #- id: rule2
      #oid: unit:#
      #prop: act
      #condition:
        #min: 1
      #run: lmacro:tests/action_started
      #args:
        #- 1
        #- 2
        #- "test"
      #kwargs:
        #from_rule: true
    #- id: rule3
      #oid: sensor:plc1/alarms
      #prop: value
      #condition: "x = 1"
      #bit: 0 # analyze bit (value only)
      #run: lmacro:tests/rule3_handler
  cycles: []
    #- id: cycle1
      #auto_start: false
      # (interval, seconds)
      #interval: 0.5
      # lmacro id to run
      #run: lmacro:tests/cycle1_handler
      # lmacro args, optional
      #args:
        #- 1
        #- 2
        #- "test"
      # lmacro kwargs, optional
      #kwargs:
        #from_cycle: true
       #error handler lmacro
      #on_error: lmacro:tests/cycle1_error_handler
  jobs: []
    #- id: job1
      # a cron-like schedule:
      # second minute hour day month weekday year
      #
      # the year field can be omitted
      # to run the task every N, use */N
      #schedule: "* * * * * *"
      #run: lmacro:tests/action_started
      #args:
        #- 1
        #- 2
        #- "test"
      #kwargs:
        #from_job: true
  openers: []
  # Openers provide generic opener robot logic for doors, windows etc
    #- oid: unit:tests/window1 # a virtual unit, which represents a door or window
      #break_on_status_error: true # break if the current state is unknown
      #logic: ac # ac (AC circuit) or rdc (reversible DC circuit)
      #port: # a single or multiple relay units, which handle power (+ for DC)
      #- unit:relays/r1
      #dport: # a single or multiple relay units, which handle direction (- for DC)
      #- unit:relays/r2
      #port_timeout: 2 # action timeout when switching assigned relay units
      #set_state: true # set the virtual unit state after successful action
      #steps: # delay (in seconds) between door/window positions, e.g. 2 steps
              # for 3 possible positions
      #- 5
      #- 2
      # tuning: 0.2 # delay (in seconds) for fully-open and fully-closed states
      #warmup_close: 0.5 # motor warmup delay on close
      #warmup_open: 1 # motor warmup delay on open
      #ts: 1 # fully close then go to N, if N <= the field value
      #te: 2 # fully open then go to N, if N >= the field value
user: nobody

Create the service using eva-shell:

eva svc create eva.controller.lm1 /opt/eva4/share/svc-tpl/svc-tpl-controller-lm.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.

action

Description	Executes an opener unit action
Parameters	See Unit actions
Returns	See Unit actions

cycle.get

Description	Gets stats for a cycle
Parameters	required
Returns	Cycle info and stats (u64 counters)

Parameters
Name	Type	Description	Required
i	String	Cycle ID	yes

Return payload example:

{
    "id": "cycle1",
    "interval": 1.0,
    "iters_err": 0,
    "iters_ok": 71,
    "status": "running",
    "timed_out": 0
}

cycle.list

Description	Lists cycles and their stats
Parameters	none
Returns	List of cycles info and stats (u64 counters)

Return payload example:

[
    {
        "id": "cycle1",
        "interval": 1.0,
        "iters_err": 0,
        "iters_ok": 71,
        "status": "running",
        "timed_out": 0
    },
    {
        "id": "cycle2",
        "interval": 1.0,
        "iters_err": 0,
        "iters_ok": 92,
        "status": "stopped",
        "timed_out": 0
    }
]

cycle.reset

Description	Resets a cycle
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	Cycle ID	yes

cycle.start

Description	Starts a cycle
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	Cycle ID	yes

cycle.stop

Description	Stops a cycle
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	Cycle ID	yes

job.get

Description	Gets a scheduled job
Parameters	required
Returns	Scheduled job info

Parameters
Name	Type	Description	Required
i	String	Job ID	yes

Return payload example:

{
    "id": "job2",
    "next_launch": "2022-05-22 22:38:50 +02:00",
    "run": "lmacro:tests/job2_handler"
}

job.list

Description	Lists scheduled jobs
Parameters	none
Returns	List of scheduled jobs infos

Return payload example:

[
    {
        "id": "job1",
        "next_launch": "2022-05-22 21:38:50 +02:00",
        "run": "lmacro:tests/job1_handler"
    }
    {
        "id": "job2",
        "next_launch": "2022-05-22 22:38:50 +02:00",
        "run": "lmacro:tests/job2_handler"
    }
]

kill

Description	Attempts to terinate/cancel all actions for an opener unit
Parameters	See Unit actions
Returns	See Unit actions

rule.get

Description	Gets a rule
Parameters	required
Returns	Rule info

Parameters
Name	Type	Description	Required
i	String	Rule ID	yes

Return payload example:

{
    "chillout_event_pending": false,
    "chillout_remaining": null,
    "chillout_time": null,
    "id": "rule1",
    "run": "lmacro:tests/temp_handler"
}

rule.list

Description	Lists rules
Parameters	none
Returns	List of rules and their info

Return payload example:

[
    {
        "chillout_event_pending": false,
        "chillout_remaining": null,
        "chillout_time": null,
        "id": "rule1",
        "run": "lmacro:tests/temp_handler"
    },
    {
        "chillout_event_pending": false,
        "chillout_remaining": null,
        "chillout_time": 10.0,
        "id": "rule2",
        "run": "lmacro:tests/on_action"
    }
]

terminate

Description	Attempts to terminate/cancel an opener unit action
Parameters	See Unit actions
Returns	See Unit actions