Understanding Tasks
Central Concepts:
The central concept of the program is that of a task.
A task is set of actions, which need to be performed when an event occurs (a trigger). For instance, a task might be to turn on the lights on the aquarium, at 8 am. In this scenario a task, consists of a triggering event (8 am), a single action (Turn on Light).
Doctor Aquarium performs tasks according to a prescribed set of task steps written in a scripting language, the instructions are called a prescription. The prescription
for this task is as follows.
if (
(todo.isHour(8))
) then
begin
Firecracker.TurnOn('A','2');
end;
If you are unfamiliar with any programming languages, this might seem intimidating, but don't worry, prescriptions are generated automatically based on selections made using a graphical user interface.
To understand how Doctor Aquarium evaluates the instruction in this prescription,
you need to be introduced to a second import concept, a plugin.
Plugins
A plugin is a packaged set of computer instructions, that you may think of as a virtual object, that has properties and methods. In this example, we have two
objects; todo, and Firecracker. The todo object has a method called isHour(), which in this case will evaluate to true if the current time is 8 am.
The Firecracker object has a method TurnOn, which will send a turn on command,
to an X-10 device with Housecode 'A', and UnitCode '2', the address of the Aquarium Lights.
The instructions for Doctor Aquarium in this task is to check if the current hour is 8 am, and if it is Turn then turn on the lights.
Task Schedule
In addition to a task prescription, a task has additional information such as property information like the task's name, and schedule information.
Doctor Aquarium is designed to evaluate multiple tasks, one task at a time, in order of a tasks refresh rate, and priority. This has implications, which you need to be aware of.
-
The program can run only a single task at a time, and tasks take time to evaluate. If one task takes a very long time to evaluate, other tasks will be delayed because of it.
-
A task's refresh rate sets how often the tasks prescript is evaluated. By default, a task is evaluated every
15 seconds. However, some tasks will need to be very responsive, and evaluated more often, and some can be evaluated rarely so you may need to adjust a tasks refresh rate. Adjusting the refresh rate on a task can save significant
processing time, and generally a task should be refreshed only as often as
needed. You may think that a task with low refresh rate may miss events, that
occurred when the task was not evaluating. But that is not true. What will happen
is that events are evaluated on weather they have occurred since the task was last refreshed, and not if the event is occurring immediately. For an extreme example, if the following script has a refresh rate of 2 hours,
and last time it has been evaluated was at 7 am, and now it is 9 am,
then the isHour(8) will evaluate to true.
if (
(todo.isHour(8))
) then
begin
Firecracker.TurnOn('A','2');
end;
This works, because the isHour() method is designed to evaluate to true as long as the hour falls between the current time, and the last time the task was evaluated.
Not all plugin methods are designed in this way. For example,
the SunMoon.Sunrise method returns the precise time of the next sunrise.
To overcome this, the built in method, isNow(event) is provided, it returns true if the time of event has occurred between the current time, and the last time the task was evaluated.
For example isNow(SunMoon.Sunrise) will evaluate to true, as long as there was a sunrise since the task was last refreshed.
Internal Representation
All task information is kept in it's own folder named after the task's name, int the tasks
directory [appdir]/data/tasks/.
A task folder holds the task script, icon, an ini file containing task properties,and log files.
A task can be shared with other people simply by giving the task's folder and it's contents. All the other person has to do is copy the the folder into their [appdir]/data/tasks/ directory, and restart the application.
Occasionally, a task may need to be managed outside the application. For example,
Doctor aquarium may have problems withe delete a task. In this case you can delete the task manually, by turning off the application, and deleting the
the task in windows explorer.