Decision Matrix Action's available for VSCP Daemon

This is decision matrix definitions for high level nodes like PC based or higher end embedded devices. The VSCP daemon is an example of this. No thoughts has been wasted on trying to minimize the use of resources like memory. Somthing that is of great importance for other parts of the VSCP protocol.

Events described here are internal to the high-end node and is therefore not visible for the nodes on the bus. On the other hand all events on the bus are also feed to the DM and events can also be sent from an element in the DM.

Action parameter is one byte with user specified content

For a high end node level I events are handled by the Level II matrix below by the Level I events being mirrored to Level II equivalents.

Action parameter is defined to be max 242 bytes (max level II actionparameter size (256-14)) with user specified content.

There is no limit in the number of DM rows available but there is naturally a practical system limit.

If an implementor wants to make the action parameter string longer this is OK. This has been done for the VSCP daemon where it can be as long as needed.

Each event that is received by the high end node is feed through the decision matrix. When the event is received it is placed on the DM input queue after passing an initial set of filter that removes events that are of no interest to the specific implemention.

The first event in the DM queue is then run through the matrix and each DM row is compared and if there is a match the action for that row is executed.

The daemon itself place some events on the DM queue. See Internal DM events below. For example the internal LOOP event is run through the matrix between every external event feed to the queue. The LOOP event will also be seen in the matrix when no other events are present. In this case a configuration value is used to set the time between two LOOP events (sleep time) if no other events arrive.

Actions can have long argument lists. If you are an end user don't be scared by this. The setup of DM rows is done with program support and you fill in the values in a nice GUI.

Note that the ampersand character ';' is used internally as a separator for arguments and if needed in an argumnt ”%;” should be used.

No operation.

Run an external program. The daemon must have execute access rights to be able to launch the program.

Parameters

• Full path to program + arguments to program. ( possibly with with substitution elements %event.class %event.type %date etc).
• Optional variable assignment.

Note that the semicolon symbol (';') is used internally and if it is part of a program argument %; should be written.

Run an external program at a specific time. The daemon must have execute access rights to be able to launch the program. When triggered it checks the time

Parameters

• Timing data as parameter 1-4 see definition below.
• Full path to program as argument 5.
• Argument to program as argument 6. (with substitution elements %event.class %event.type %date etc).
• Optional variable assignment

Parameters

• The DLL is loaded at startup where the dll ordinal n is assigned.
• Argument 1 is the name of the method.
• Optional variable assignment

Dll's are loaded when the DM matrix is loaded. Each method that is named gets a method assigned This method should accept a single utf8 string as an argument and return an int16_t value which if positive or zero indicates a positive execution or if less then zero a negative result of the execution.

Parameters

• The DLL is loaded at startup where the dll ordinal n is assigned.
• Argument 1 is the name of the method.
• Optional variable assignment

Store the data in a variable. The variable is named in the argument.

Parameters

• Variablename with assignment

Example parameter data

$Running=false        // set a boolean variable to false.
$Name="Mike Hood"     // set variable name to a string.
$Level=%event.data.1  // Set variable level to value of data byte 1.

Add the data to a variable. The variable is named in the argument.

Parameters

$variable,value to add

If the variable does not exist it is created.

Subtract the data from a variable. The variable is named in the argument.

Parameters

$variable, value to subtract

Multiply the data with a variable. The variable is named in the argument.

Parameters

 $variable, Value to multiply variable with

Divide the data with a variable. The variable is named in the argument.

Parameters

$value, value to divide variable with

Send event when another event is received.

Parameters

• Event to send.
• Optional variable that will be set to false.

Send an event until a timeout occurs and when a specified variable is set to false.

This action is specified to make it possible to define DM enteries that wait for a response form a node and resend a specified event a number of times until this response is received or a timeout occured.

Parameters

• Control variable name.
• Event to send before giving up..
• Timeout in milliseconds.
• Custom event to send on timeout.

This is done by use of a variable. The variable is set to false by the action that initially sent the event that needs a reply. When the variable is false this event get triggered and will start to send periodic events until the wanted event is actually is received and at which point the variable is set to true again.

A timeout event is sent if a timeout occurs. Variable is set to true.

Note that the filter/mask should not be set for some of the internal time events (loop, second, minute etc). This choice determines the interval between events.

To get all this to work three DM rows are required

1. A row that send the original event and flag the above event.
2. The above event which resends until response received.
3. A row that reset the flag when the reply is received (Store in variable).

This action sends event(s) from a named file.

Parameters

• path to file
• timing data

This is a future action that runs an internal script given as a parameter.

Parameters

• script

This is a future action that runs an internal script at a specific time given as a parameter.

Parameters

• Timing data as parameter 1-4 see definition below.
• script

This action starts a timer identified by a 32-bit id that will count down from a specified time set as HH:MM.SS:ms. If the timer is already define it will be reused and if active it will be reinitialized.

Parameters

• timer id.
• Start time as HH:MM:SS:ms

This action pause an active timer identified by a 32-bit id. If the timer does not exist the action does nothing.

Parameters

• timer id.

This action resume a paused timer identified by a 32-bit id. If the timer does not exist or is active the action does nothing.

Parameters

• timer id.

This action stops an active timer identified by a 32-bit id. If the timer does not exist or is inactive the action does nothing.

Parameters

• timer id.

This action writes (appends) the trigger event to a file. The written format is XML.

Parameters

• path to file
• user specified string (substitutions below can be used in the string).

DM events is a special type of events that just are available in the DM loop and is generated internally by the daemon.

The available events is defined here .

1. String with days the action can occur in as mtwtfss- use '-' for day when action should not be performed.
2. Start Data/time for when the action can occur in ISO format as YYYY-MM-DD HH:MM:SS Use a wildcard character '*' if any of them is don't care.
3. End Data/time for when the action can occur in ISO format as YYYY-MM-DD HH:MM:SS Use a wildcard character '*' if any of them is don't care.
4. Action date/time when action should occur in ISO format as YYYY:MM:DD HH:MM:SS

The start and the end Date/time fields set the date/time range when the action is allowed to occur.

The action date set the date/time when the action should occur. This can be a one shot in which case the full date/time is filled in as in 2009-11-02 14:30:00 which will perform action at this time once if the start/end dates allow for that. To get repeats it is possible to use wildcards. For example *-*-* 14:30:* (can also be written as * 14:30:*) will perform the operation every seconds from 14:30 to (but not including) 14:31 in the time range set by the start/end date/time range.

For repeating operation that is just dependent on time filter on the SECOND event so that this is the only event that trigger the row.

It is also possible to specify more then one of each element in the date/time by separating them with a slash. For example * 14:0/10/20/30/40/50:00 will do the action every ten minutes between two a clock and three a clock in the afternoon.

This functionality is provided as dll/dl with the package. It is not built into the daemon itself because of portability of the daemon itself.

First argument is receiver, second argument is subject, third argument is content.

First argument is receiver, second argument is subject, third argument is content.

Only argument is URL.

All string substitution keyworkds are precided with a %

%%                  - The character '%'
%;                  - The character ';'. Semicolon normally separates arguments of an action.
%cr                 - A carriage return.
%lf                 - A line feed.
%crlf               - A carriage return + a line feed
%tab                - A tab.
%bell               - A bell. 
%event              - A full event in the standard form
%event.class        - The class for the event
%event.type         - The type for the event.
%event.head         - head of the event.
%event.priority     - The priority for the event.
%event.data         - All databytes as a comma separated list.
%event.data.n       - Data byte n
%date               - Date in ISO format YY-MM-DD
%time               - Time in ISO form HH:MM:SS.
%hour               - Current hour.
%minute             - Current minute.
%second             - Current second.
%week               - Current week number (1-52).
%month              - Current month number (1-12).
%year               - Current year.
%quarter            - Current quarter(1-4).
%uptime             - Machine uptime.
%$xxxx              - value of varible 'xxxxx'. Use '%$$' to represent '%$'.

Can perfectly be used as arguments for triggered external program execution.

1. Set filter to see only the TURN-ON command and possibly zone (second data byte) and subzone (third data byte) if only interested in a specific location.
2. The Action code is set to Run external program.
3. First parameter is path to program
4. Second parameter is argument to program.

use substitutions as of above for the arguments if event data should be transfered to the external program.

The external program heyu is used to control X10 devices. Here we want to turn on a group of lamps at 18:00 each night except during the summer. But never do this on saturdays.

1. Set filter/Mask so only the SECOND internal daemon event is interesting.
2. The Action code is set to Run external program at specific time.
3. First parameter is set to mtswtf-s to allow the action to take place all days except saturday.
4. Second parameter is 10-01;04-01 to allow the action to occur from October first to April first our summer definition.
5. Third parameter is *:*;*:* as we have no timing constraints.
6. Fourth paremeter is *-*-* 18:00:00 the time we want the lamp to turn on.
7. Fifth parameter is path to heyu
8. Sixth parameter is argument to heyu. In this case “on A13” to turn on switches set to A13.