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.
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()])
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 ifTrue
, 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.
-