LOT Actions
1. Introduction
The Coreflux LOT scripting language is used to define Actions—small logic blocks that react to events (time-based or topic-based) and publish data to topics. This document details each element of the syntax so you can understand how LOT interprets your code.
For practical examples of LOT Actions, check out the Actions examples in the LOT Samples Repository.
1.1 Overall Structure
Each Action starts with the keyword:
followed by one of the event triggers (e.g., ON EVERY ...
, ON TOPIC ...
, etc.) and a logic block describing what to do when that event occurs. Within the logic block, you can use IF statements, or simply do one or more PUBLISH
instructions.
Example structure:
1.2 Indentation
LOT uses indentation to visually separate blocks of code and highlight logic flow. While indentation levels can be set by tabs or spaces, be consistent.
- Top-level lines (like
DEFINE ACTION MyAction
andON EVERY 5 SECONDS DO
) begin at the leftmost column. - Nested lines (the statements inside the
DO
block, or inside anIF THEN
orELSE
block) are indented.
This helps LOT (and readers) understand which statements belong to which blocks.
2. Event Triggers
An Action is activated by specifying the condition or event that should trigger its execution. Some common triggers are:
- ON EVERY
<time>
– runs on a repeating interval. - Example:
ON EVERY 5 SECONDS DO
executes the block every 5 seconds. -
Other intervals can be
MINUTES
,HOURS
, etc. -
ON TOPIC
<topic>
– runs whenever the specified topic is published to. - Example:
ON TOPIC "myTopic" DO
executes whenever a message arrives on"myTopic"
.
3. Expressions in LOT
LOT expressions can retrieve data from a topic, compare values, or perform mathematical operations.
3.1 GET TOPIC "<topic>"
Retrieves the most recent payload of a specific MQTT topic.
Example:
3.2 Mathematical Operations
The following operators are supported on numeric values:
+
(addition)-
(subtraction)*
(multiplication)/
(division)%
(modulo, returns the remainder of a division)
Example:
3.3 Comparisons
You can compare values using ==
, !=
, <
, >
, <=
, >=
, etc.
Example:
(Both ==
and =
can be used in certain comparisons; it depends on your broker's LOT version. Check your Coreflux documentation.)
4. The IF THEN ELSE
Logic
LOT supports conditional logic through an IF <expression> THEN
and optional ELSE
:
- Condition: A boolean expression (e.g.,
GET TOPIC "switchState" == "off"
). - THEN block: One or more PUBLISH statements (or other logic).
- ELSE block (optional): Executed when the condition is not met.
Example:
IF GET TOPIC "my/light" == "off" THEN
PUBLISH TOPIC "my/light" WITH "on"
ELSE
PUBLISH TOPIC "my/light" WITH "off"
5. Special Keywords
5.1 PAYLOAD
PAYLOAD refers to the value that triggered the Action in an ON TOPIC
event. Whenever an action is triggered by a topic publication, PAYLOAD
holds that newly published value.
For instance, in an action triggered by ON TOPIC "input2/topic"
:
DEFINE ACTION MyAction
ON TOPIC "input2/topic" DO
PUBLISH TOPIC "some/otherTopic" WITH (PAYLOAD + 1)
- Here,
PAYLOAD
is the last message content published toinput2/topic
. (PAYLOAD + 1)
increments that value, then publishes the result.
5.2 TIMESTAMP
TIMESTAMP is used to insert the current date/time (in UTC or local format, depending on your syntax) into the published data.
- This sends a message to
"my/topic"
that contains a JSON object or string with the current UTC time (exact format may depend on your Coreflux version).
6. Example Actions
Below are four sample Actions demonstrating the syntax.
6.1 StrokeGenerator
DEFINE ACTION StrokeGenerator
ON EVERY 5 SECONDS DO
IF GET TOPIC "Coreflux/Porto/MeetingRoom/Light1/command/switch:0" == "off" THEN
PUBLISH TOPIC "Coreflux/Porto/MeetingRoom/Light1/command/switch:0" WITH "on"
PUBLISH TOPIC "Coreflux/Porto/MeetingRoom/Light1/command/switch:0/counter" WITH (GET TOPIC "Coreflux/Porto/MeetingRoom/Light1/command/switch:0/counter" + 1)
ELSE
PUBLISH TOPIC "Coreflux/Porto/MeetingRoom/Light1/command/switch:0" WITH "off"
- Trigger: Every 5 seconds.
- Logic:
- Retrieves the current state of
"Coreflux/Porto/MeetingRoom/Light1/command/switch:0"
. - If that state is
"off"
, turn it"on"
and increment its counter. - Otherwise, turn it
"off"
.
6.2 ChangeOfTopic
DEFINE ACTION ChangeOfTopic
ON TOPIC "input2/topic" DO
PUBLISH TOPIC "input2/topic" WITH (PAYLOAD + 1)
- Trigger: A message is published to
"input2/topic"
. - Logic:
- Whatever the
PAYLOAD
is (assuming it's numeric), increment it by 1, then publish the new value back to the same topic.
6.3 SHOWTIMEEVERY5SECONDS
DEFINE ACTION SHOWTIMEEVERY5SECONDS
ON EVERY 5 SECONDS DO
PUBLISH TOPIC "input2/topic" WITH TIMESTAMP "UTC"
- Trigger: Every 5 seconds.
- Logic:
- Publish the current UTC time to
"input2/topic"
.
6.4 CheckIfPar
DEFINE ACTION CheckIfPar
ON EVERY 1 MINUTE DO
IF (GET TOPIC "input2/topic" % 2) = 0 THEN
PUBLISH TOPIC "teste" WITH "pair"
ELSE
PUBLISH TOPIC "teste" WITH "odd"
- Trigger: Every 1 minute.
- Logic:
- Checks the value of
input2/topic
. - If that value is even (
% 2 = 0
), publish"pair"
toteste
. Otherwise, publish"odd"
.
7. Adding or Removing Actions
To add an Action in Coreflux, you publish its entire DEFINE ACTION
snippet to the special system topic "$SYS/Coreflux/Command"
, using the parameter -addAction
.
Example: Add StrokeGenerator
:
Topic: $SYS/Coreflux/Command
Payload:
publish -addAction
DEFINE ACTION StrokeGenerator
ON EVERY 5 SECONDS DO
IF GET TOPIC "Coreflux/Porto/MeetingRoom/Light1/command/switch:0" == "off" THEN
PUBLISH ...
...
Once accepted, the broker will store and run this Action. You can confirm it by checking "$SYS/Coreflux/Actions"
.
Removing Actions
Similarly, to remove an existing Action, publish to the same system topic with -removeAction <ActionName>
:
8. Important
- Indentation clarifies logic blocks and nested statements.
- Expressions let you retrieve topic payloads, do math, and compare values.
- IF THEN ELSE controls logic flow based on your conditions.
- PAYLOAD references incoming data; TIMESTAMP injects the current time.
- Events can be triggered by time intervals (
ON EVERY
) or by topic messages (ON TOPIC
).
With these fundamentals, you can create custom Actions to automate logic within the Coreflux broker using LOT.
How LOT Actions Work
LOT Actions within Coreflux operate on two primary triggering mechanisms and follow a specific execution model designed for real-time IoT environments.
Action Triggers
Actions can be triggered in two ways:
graph TB
subgraph "Action Trigger Mechanisms"
A[LOT Action] --> B{Trigger Type}
B -->|Time-based| C[Scheduled Execution]
B -->|Topic-based| D[Event-driven Execution]
end
subgraph "Time-based Execution"
C --> C1[System checks every second]
C1 --> C2[Compares current time with\naction's scheduled time]
C2 --> C3[Executes if time condition met]
C3 --> C4[Updates timestamp for\nnext execution]
end
subgraph "Topic-based Execution"
D --> D1[Monitor subscribed topics]
D1 --> D2[Topic published]
D2 --> D3[Immediately execute action]
end
Time-based Triggers
Time-based actions function on a scheduled basis (every minute, hour, day, week, or month):
- The Coreflux system maintains a task that runs every second
- This task checks all time-based actions to determine if they need to be executed
- Each action has a timestamp based on its previous execution
- When the scheduled time is reached, the action is triggered
- After execution, the timestamp is updated for the next scheduled run
For example, an action scheduled to run every hour will be checked by the system each second, but will only execute when the hour interval has elapsed since its last execution.
Topic-based Triggers
Topic-based actions are event-driven and execute in response to MQTT messages:
- These actions monitor specific topics
- When a message is published to a monitored topic, the action is triggered immediately
- This allows for real-time response to events in the system
- Topic-based actions can create chains of execution, where one action's output triggers another action
Action Execution Model
LOT Actions follow a Programmable Logic Controller (PLC)-like execution model:
sequenceDiagram
participant Topic System
participant Action Engine
participant Action Logic
Note over Topic System,Action Logic: Execution Flow
Topic System->>Action Engine: Trigger (time or topic)
Action Engine->>Topic System: Take snapshot of relevant topics
Action Engine->>Action Logic: Process with inputs from snapshot
Action Logic->>Action Engine: Return results
Action Engine->>Topic System: Publish output topics
Note over Topic System: Other actions may be triggered by outputs
The execution process works as follows:
-
Input Snapshot: When an action is triggered, the system takes a "snapshot" of all topics relevant to the action, capturing their current state.
-
Processing: The action executes using the input snapshot, ensuring it works with a consistent view of the system state at the time it was triggered.
-
Output Flush: After execution completes, the action "flushes" its outputs by publishing to the defined topics.
-
Cascading Actions: These output topics may trigger other actions, creating a cascading flow of operations.
This execution model ensures deterministic behavior and allows for complex event processing chains while maintaining system stability.
graph LR
subgraph "Action Execution"
A[Trigger] --> B[Input Snapshot]
B --> C[Process Logic]
C --> D[Output Flush]
D --> E[Potential Cascade]
end
subgraph "Input Sources"
F1[Topic A] --> B
F2[Topic B] --> B
F3[System State] --> B
end
subgraph "Output Destinations"
D --> G1[Topic X]
D --> G2[Topic Y]
end
G1 --> H[Another Action]
This approach enables sophisticated automation workflows where actions can be sequenced, conditional operations can be performed, and complex event processing chains can be established.
Rules and Command Processing
While Actions handle event processing and automation, Rules govern permissions and system operations. Rules are triggered when specific operations are requested, controlling whether those operations are allowed to proceed.
graph TB
A[Command] --> B{CommandCall Rule}
B -->|Approved| C{Specific Rule}
B -->|Rejected| D[Command Denied]
C -->|Approved| E[Command Executed]
C -->|Rejected| D
The command processing flow:
- Any command first passes through the
CommandCall
rule - If approved, it then passes to the specific rule type for that command
- Only if both rules approve will the command execute
Common rule types include:
Rule Category | Examples |
---|---|
Topic Access | Subscribe , SubscribeSys , Publish , PublishSys |
User Management | UserManagementCreation , UserManagementPasswordChange , UserManagementUpdate , UserManagementRemove |
Asset Management | AssetManagementCreation , AssetManagementRemove , AssetManagementStart |
Action Management | ActionManagementCreation , ActionManagementRemove , ActionManagementRun |
Rule Management | RuleManagementCreation , RuleManagementRemove |
Model Management | ModelManagementCreation , ModelManagementRemove |
Route Management | RouteManagementCreation , RouteManagementRemove |
System | SystemConfiguration , CommandCall , ShellCommand |
This rule hierarchy ensures that system operations follow proper authorization protocols and helps maintain system security and integrity.