Programming Automate Objects

Programs

Program features are defined in ProgrammableSystemObject class. Program, DefaultProgram and StatusObject classes are subclassed from ProgrammableSystemObject, as can be seen in the following inheritance diagram.

Inheritance diagram of automate.program.Program, automate.program.DefaultProgram, automate.statusobject.StatusObject, automate.statusobject.AbstractSensor, automate.statusobject.AbstractActuator

Programs are used to define the logic on which system operates. Program behavior is determined by the conditions (active_condition, update_condition) and actions (on_activate, on_update, on_deactivate), that are of AbstractCallable type. Callables are special objects that are used to implement the actual programming of Automate program objects (see Callables). There are many special Callable classes to perform different operations (see Builtin Callables) and it is also easy to develop your own Callables (see Deriving Custom Callables).

All Sensors and Actuators that affect the return value of a condition callable, are triggers of a Callable. All actuators (and writeable sensors) that a callable may change, are targets. Whenever any of the triggers status change, programs conditions are automatically updated and actions are taken if appropriate condition evaluates as True.

Actions and conditions are used as follows. Programs can be either active or inactive depending on active_condition. When program actives (i.e. active_condition changes to True), on_activate action is called. When program deactivates, on_deactivate, action is called, correspondingly. When program is active, its targets can be continuously manipulated by on_update callable, which is called whenever update_condition evaluates as True.

Actuator Status Manipulation

Program can control status of one or more actuators. Programs manipulate Actuator statuses the following way:

  • One or more programs can control state of the same Actuator. Each program has priority (floating point number), so that the actual status of Actuator is determined by program with highest priority
  • If highest priority program deactivates, the control of Actuator status is moved to the the second-highest priority active program.
  • If there are no other Program, each Actuator has also one DefaultProgram, which then takes over Actuator control.

The following example application illustrates the priorities:

from automate import *
class MySystem(System):
    low_prio_prg = UserBoolSensor(priority=-5,
                                  active_condition=Value('low_prio_prg'),
                                  on_activate=SetStatus('actuator', 1.0),
                                  default=True,
                                  )
    med_prio_prg = UserBoolSensor(priority=1,
                                  active_condition=Value('med_prio_prg'),
                                  on_activate=SetStatus('actuator', 2.0),
                                  default=True,
                                  )
    high_prio_prg = UserBoolSensor(priority=5,
                                  active_condition=Value('high_prio_prg'),
                                  on_activate=SetStatus('actuator', 3.0),
                                  default=True,
                                  )
    inactive_high_prio_prg = UserBoolSensor(priority=6,
                                  active_condition=Value('inactive_high_prio_prg'),
                                  on_activate=SetStatus('actuator', 4.0),
                                  default=False,
                                  )

    actuator = FloatActuator()

ms = MySystem(services=[WebService()])
_images/program.svg

In this application, four programs (three manually defined programs and DefaultProgram dp_actuator) are active for actuator. The actual status of actuator (now: 3.0) is determined by highest priority program. If high_prio_prog goes inactive (i.e. if its status is changed to False):

high_prio_prg.status = False

the status is then determined by med_prio_prg (=> 2.0). And so on. All the active programs for actuator are visible in UML diagram. Red arrow shows the dominating program, blue arrows show the other non-dominating active programs and gray arrows show the inactive programs that have the actuator as a target (i.e. if they are activated, they will manipulate the status of the actuator). low_prio_prg can never manipulate actuator status as its priority is lower than default program dp_actuator priority.

Program Features

Program features are defined in ProgrammableSystemObject class. Its definition is as follows:

Note

Unfortunately, due to current Sphinx autodoc limitation, all trait types are displayed in this documentation as None. For the real trait types, please see the source fode.

class automate.program.ProgrammableSystemObject(*args, **kwargs)[source]

System object with standard program features (i.e. conditions & actions).

active_condition = None

A condition Callable which determines the condition, when the program is activated. Program deactivates, when condition turns to False. When program is activated, on_activate action is executed. When program deactivates. on_deactivate is executed.

on_activate = None

An action Callable to be executed when Program actives.

on_deactivate = None

An action Callable to be executed when Program deactivates.

update_condition = None

When program is active, this is the condition Callable that must equal to True in order to on_update action to be executed. Whenever a trigger is changed, this condition is checked and if True, on_update is executed.

on_update = None

Action Callable to be executed if Program is active and update_condition is True.

priority = None

When programs sets Actuator status, the actual status of Actuator is determined by a program that has highest priority. Lower priority programs are stacked and used only if higher priority programs are deactivated.

active = None

Is program active? Automatically changed. In UIs you can fake the program active status by changing this. Normally do not change manually.

status = None

Status property is introduced to have interface compability with Status objects. For plain Programs, status equals to the result of its active condition Callable.

actual_triggers = None

(read-only property) Set of triggers, that cause this Program conditions to be checked (and actions to be executed). This data is updated from custom triggers list, conditions and actions.

actual_targets = None

(read-only property) Set of targets that this Program might touch. This data is updated from custom targets list and actions.

triggers = None

Custom set of additional triggers, whose status change will trigger this Program conditions/actions

exclude_triggers = None

Triggers in this set do not trigger the program actions/conditions even if they are introduced by Callables etc.

targets = None

Additional targets. Not usually needed, but if you want to set status for some reason by some custom function, for example, then you need to use this.