Reactions and tasks¶

The Reactions and tasks page allows you to configure reactions (very similar to events in LK3) and tasks (similar to the scheduler on LK3).

Basically, there are 4 sections on Reactions and tasks page:

Buttons for saving and discarding changes. If there are some changes they will be enabled (can be clicked). Above these buttons you will find alerts about unsaved changes, status of configuration save.
A services tab in which you can add, edit and list service configurations.
A reactions tab in which you can add, edit and list reactions.
A tasks tab where you can add, edit and list tasks.

Services, reactions and tasks tabs are very similar visually. There is a counter showing their number, a button to open form for adding new, a list of configured items. The list shows details and includes buttons to edit or delete items.

Saving changes

There is a message displayed when there are unsaved changes, so you won't forget about it and lose your changes. It's recommended to save after batch of changes, not single ones, or in other words do in once you have finished applying changes (to actually lose them you would have to close Reactions and tasks tab in browser).

Services¶

Service configurations are the basis of Reactions and tasks, because they are required to create reactions and therefore are important for tasks (task can trigger reactions). Service configuration defines basic options for service, eg. for smtp (email) it defines address to which messages can be send.

Currently there are few supported services:

smtp - send email (for now only account used to register the account can be notified)
mqttpub - send MQTT message (can be used to control LK3)
thingspeak - send message to update thingspeak's channel

Adding service¶

Adding or configuring service is nothing more but giving common name to let's say sending email to your email address or sending MQTT message to LK3 command topic. The goal behind it is to have pool of "actions" that can be used in reactions, where you will define the actual message to send or under what conditions it should happen, but more about it in reactions section.

Form for adding a new service configurations is shown on the picture below. There are 3 fields:

Name of configuration, can contain letters, digits and _. It has to be unique, that is you can't have two service configurations with the same name. It might be a good idea to choose descriptive name, that will let you easily distinguish configurations, eg. mymailnotification for sending email to own email address. In other parts of Reactions and tasks, name will be visible in pairs with the name of the service.
Name of service/function you can use with short description of it. List of supported services will be extended later on.
Value is essential part of configuration of service, for example smtp's value is email address to notify, mqttpub's value is MQTT publish topic. Field differs depening on chosen service, eg. for mqttpub it is a text input and a dropdown list of topics associated with your devices.

Services list¶

List of configured services with their details and buttons for editing or deleting. There are 4 columns:

Name of configuration.
Name of service for which this configuration is.
Value, which depending on the service displays email address (for smtp), MQTT topic (for mqttpub).
Buttons to edit and delete service configuration. Note that these actions can affect reactions in which service is used. In case of deletion there will appear information which reactions will be changed or even deleted, but editing will update related reactions silently.

Reactions¶

Reactions are actions to be performed in response to an incoming MQTT message on a specific topic (e.g. from a device). The actions to be performed are defined by service configurations. There are also modifiers, such as a value filter, a time filter, a suppression and a format, that allow to specify conditions under which the action should be performed.

Value filter¶

Very important part of reaction is value filter, because it allows to take action based on content of message, not only the fact that there was a message on specific topic. For now there are two versions that can work on numeric values, eg. sensor reading, out status. They compare received value with the one given in reaction setup, and if the result of comparison is true it will pass message to actions, else it will not take further actions.

Currently available are following versions of value filter:

Basic - performs simple mathematical comparison of received numeric value with given static value.
Advanced - performs two mathematical comparison and then logical conjunction or disjunction of comparison's results.

Time filter¶

It defines period of time, when the reaction can trigger its services.

Suppression¶

It suppresses consequetive invokes of a reaction for given period of time after the reaction was executed. Can be used to limit execution of certain reaction, eg. send notification via email once and then suppress following invokes of the reaction for 30 minutes (instead of sending email on every MQTT message).

In case the reaction topic subscription contains special characters like + or # (details here) then suppression is checked separately for each unique topic of message.

Tracking the connection state of LK HW 3.5+

In LK HW 3.5+, an LWT function is available in the MQTT client, which results in publishing the MQTT connection status of LK on the topic prefix/connected - 1 when connected and 0 when disconnected.

Using this functionality, we can use one reaction to define notifications about the loss of LK HW 3.5+ connectivity with the MQTT server. Below is an example how to do it.

We create reaction with the topic [user prefix]/+/connected, value filter < 1 (true for 0), suppression with value 1800 (30 minutes), and action smtp (which will send notifications to our email address), with the format Status of LK on {topic} changed to offline.

This reaction will react to messages with the content 0 on topics that match the prefix/+/connected subscription, e.g. prefix/lk1/connected, prefix/lk2/connected. As a result, the reaction will send notifications about connection loss of each LK at most once every 30 minutes (the suppression time will be counted separately for each device/topic). It is worth noting that the notification can also be sent as a result of a normal LK restart.

Format¶

Format allows to overwrite received message's text before it is passed to services for processing, but after it was checked by filter. You can use special tags {topic} and {payload} in format, so they will be replaced in message with actual topic on which message was received and message's content respectively. Thanks to that you can send more human-like message via email by wrapping sensor reading into full sentence.

Let's say for example, a format with the following content:

The temperature in living room is {payload} from DS sensor on topic {topic}

Then on the associated topic dev1/temp arrives message 25, and format changes it to:

The temperature in living room is 25 from DS sensor on topic dev1/temp

Adding reactions¶

Form for adding new reaction is shown on the picture below. There are following fields:

Name of reaction, can contain letters, digits and _, and has to be unique among reactions.
MQTT subscription topic that will be source of messages to process by filter, format and services.
Filter type and its configuration. Fields for entering configuration appear when filter is chosen, they include reference values, comparison operators and logical operator.
The beginning and end of the interval in which the condition is met.
Reaction suppression expressed in seconds.
Format is a text that will overwrite original message before passing it to service (more about it above).
Select which actions (services) should be taken if filter result is True (always True when not used). The list is populated with your configured services, so make sure you have at least one, otherwise you won't be able to set reaction.

To configure a reaction you have to set a name, a topic and the services. Other fields are optional and can be used to modify how the reaction works.

Reactions list¶

List of reactions with their details and buttons for editing or deleting. There are 6 columns:

Name of reaction.
Topic from which messages will be processed.
Configurations of filters and suppression. If set they are prefixed with V: (value filter), T: (time filter) and S: (suppression), else empty.
Text of format (empty if not set).
Services that will be run for received (or formatted) message. They are displayed in pairs, that is service name tied with your custom configuration name.
Buttons to activate, edit and delete reaction.

Tasks¶

Tasks consist in sending MQTT messages to specific topics at specified times, in a periodic manner. Therefore, they act as mqttpub service themselves, but when paired with reactions they can perform more functions (any attached to reaction, eg. send email).

Adding task¶

Form for adding a new task is shown on the picture below. There are 4 fields:

Name of task, can contain letters, digits and _, and has to be unique among tasks.
MQTT publish topic to which message will be published. Next to the input field there is a dropdown list with command topics for your devices and reactions. Note that reaction topic can include special characters (# or + used in MQTT subscriptions), which cannot be used in publish topic, therefore you will have to replace them after picking from list.
Time and weekdays when the message should be send. At least one weekday has to be selected.
Message to send. Note that if message is send to topic with configured filters or format, this message will be processed by them.

Tasks list¶

List of tasks with their details and buttons for editing or deleting. There are 5 columns:

Name of task.
Topic to which message should be send.
When the message should be send.
Text of message to send.
Buttons to activate, edit or delete task.