triggers

Triggers

So far there have been multiple ways introduced that cmd's can be triggered. The aim of this document is to give a general overview of these methods and show how they can interact.

Hardware triggers

Triggers that are independent of the data that was received but on hardware instead.

Program

<!-- Startup: By default all tasks that have a trigger will be run on startup of dcafs -->
<task output="system" trigger="delay:5s">cmd</task> <!-- triggers the cmd 5 seconds after startup -->

<!-- Shutdown: dcafs will try to execute the taskset (of all taskmanagers) with id 'shutdown' when it's about to shutdown -->
<tasket id="shutdown" run="oneshot">
    <task output="system" >cmd1</task>
    <task output="system" >cmd2</task>
    <task output="system" >cmd3</task>
</tasket>

<!-- (linux only) Wokeup: when the device was put to sleep with dcafs, it triggers on waking up again -->
<!-- Either a single task -->
<task id="wokeup" output="system" >cmd1</task>
<!-- Or a taskset -->
<tasket id="wokeup" run="oneshot">
    <task output="system" >cmd1</task>
    <task output="system" >cmd2</task>
    <task output="system" >cmd3</task>
</tasket>

Connection triggers

These are triggered based on what happens with a connection.

    <stream id="streamid" type="tcp">   
        <address>localhost:4000</address>        
        <cmd trigger="open">cmd</cmd>   <!-- triggers when the connection is opened-->
        <cmd trigger="close">cmd</cmd>  <!-- triggers when the connection is closed -->
        <cmd trigger="idle">cmd</cmd>   <!-- triggers when the connection is idle -->
        <cmd trigger="!idle">cmd</cmd>  <!-- triggers when the connection is no longer idle -->
    </stream>

Data triggers

These trigger when a rtval is a certain value.

<!-- If every single change of the data needs to be checked -->
<rtvals>
    <double id="datapoint" unit="things">
        <cmd when="from 1 to 10">cmd1</cmd> <!-- triggers when datapoint goes between 1 and 10  -->
        <cmd when="below 0">cmd2</cmd>      <!-- Triggers every time the datapoint goes below 0 -->
    </double>
</rtvals>
<!-- If the data arrives faster than a check is required -->
<task output="manager" trigger="delay:0s">taskset:check</task>
<taskset id="check" run="step" repeat="-1"> <!-- infinite runs -->
    <!-- This checks every 10s to see if the datapoint is between 1 and 10 -->
    <task output="system" 	trigger="retry:10s,-1"		req="datapoint not below 1 and datapoint not above 10">cmd1</task>
    <!-- This waits for the value to go outside the range again -->
    <waitfor 	interval="10s"	checks="1" req="datapoint below 1 or datapoint above 10"/>
</taskset>
<!-- 
    Note1: the 'req' looks a lot more complicated than in rtvals because it needs to parse id's and could contain
    math operations.
    Note2: The task version has the added advantage that you could increase the amount of successive valid checks needed
    to prevent the trigger to happen if the value is 'hovering' around 1 or 10. 
--> 

Time & Place

Triggers that depend on the current time, elapsed time or coordinates received.

Time

This is done using the TaskManager functionality.

<task output="system" trigger="delay:1h">cmd1</task>            <!-- Execute with a one hour delay -->
<task output="system" trigger="time:08:00">cmd2</task>          <!-- Execute daily at 8 o'clock UTC -->
<task output="system" trigger="time:08:00,weekday">cmd3</task>  <!-- Execute every weekday at 8 o'clock UTC -->
<task output="system" trigger="localtime:18:00,motufr">cmd4</task> <!-- Execute on monday, tuesday and friday at 18 o'clock localtime -->

Waypoints

Waypoints allow you to trigger cmd's based on travel to/from a waypoint.

    <waypoints latval="lat_rtval" lonval="lon_rtval" sogval="sog_rtval">
      <waypoint id="wp_id" lat="1" lon="1" range="50">
          <name>dock</name>
          <!-- Going further away than 50m from wp_id and do this with a bearing between 180° and 360° -->
          <travel id="leaving_wp_id" dir="out" bearing="from 180 to 360">
              <cmd>cmd1</cmd>
              <cmd>cmd2</cmd>
          </travel>
          <!-- Coming closer to wp_id than 50m and do this with a bearing between 1° and 180° -->
          <travel id="return_wp_id" dir="in" bearing="from 1 to 180">
              <cmd>cmd3</cmd>
              <cmd>cmd4</cmd>
          </travel>
      </waypoint>
    </waypoints>

Combinations

These go from really simple:

<!-- Time & data -->
<task output="system" trigger="time:08:00" req="datapoint below 50">cmd</task>
<!-- Hardware & data -->
<task id="wokeup" output="system" req="datapoint below 50">cmd</task>

Given that task(set)s can be started with a cmd, it's fairly straightforward to combine them.

<!-- When the stream is no longer idle and the last received data is below 50 -->
<stream id="streamid" type="tcp">
    <address>localhost:4000</address>
    <cmd trigger="!idle">tm:dothis</cmd>  <!-- triggers when the connection is no longer idle -->
</stream>
<!-- Taskmanager with id tm -->
<task id="dothis" output="system" req="datapoint below 50">cmd</task>