Skip to content

LOT Language - Model Management Documentation

1. Overview

Models in Coreflux use the LOT language syntax to define how data is processed, transformed, and published. Models take input data (triggered by specific topics), process it through expressions, constants, or transformations, and output the results to new MQTT topics.

Models serve as data pipelines or virtual sensors that can enrich data from existing MQTT topics, perform computations, and publish processed results. By using LOT language models, you can easily configure and maintain logic at the broker level, enabling dynamic calculation and formatting of data without the need for external services.

2. Model Mechanism

2.1 Model Processing Overview

Models operate as functions or pipelines triggered whenever their input topics receive new messages. When a trigger topic updates:

  1. Input Acquisition: The model reads the defined input properties. Some properties may be constants, others may reference topics.
  2. Computation and Expressions: Each property's definition can involve direct values, references to other properties, or arithmetic/conditional expressions.
  3. Output Publishing: After processing, the model publishes each property’s current value to the model's output namespace, essentially creating a set of derived topics.

Models can thus aggregate or transform data from multiple inputs and produce consolidated or computed outputs.

2.2 Properties in Models

Each model consists of one or more properties defined with the ADD statement. A property can be:

  • Directly from a Topic (with AS TRIGGER or without): If AS TRIGGER is used, changes in that topic will cause the model to recompute and update outputs.
  • A Fixed Constant: A property can be assigned a static number or string.
  • An Expression: A property can be computed from other properties using arithmetic operations, conditional expressions (IF ... THEN ... ELSE), or timestamps.

2.3 Topics and Unified Namespace

Models can use wildcards (+) in their topics to dynamically handle multiple sources in a Unified Namespace (UNS). For example, if a model's output topic is Coreflux/+/+/+/+/energy, and it references an input topic shellies/+/+/+/+/device/energy as a trigger, then any shellies/x/y/z/w/device/energy incoming value will map to Coreflux/x/y/z/w/energy/... outputs.

2.4 Constants and Expressions

Properties can hold constant values or can be computed using arithmetic operations, conditional logic, or timestamps. For example:

  • Constant: ADD "energy_price" WITH 3
  • Expression: ADD "cost" WITH (total_energy * energy_price)

These capabilities allow building complex logic directly in the broker without external code.

3. Default Behavior

By default, models do not apply any transformations unless defined. They do not alter the original incoming data but produce new topics for processed results. If a model references a topic that never updates, the model will not publish new outputs.

4. Model Syntax

Models in the LOT language follow this general syntax:

DEFINE MODEL <model_name> WITH TOPIC "<output_base_topic>"
    ADD "<property_name>" WITH TOPIC "<input_topic>" [AS TRIGGER]
    ADD "<property_name>" WITH <constant_value>
    ADD "<property_name>" WITH (expression)

4.1 Components Explained

  • DEFINE MODEL <model_name>: Defines a new model with a unique <model_name>.
  • WITH TOPIC <output_base_topic>: Specifies the base output topic for the model’s computed properties.
  • ADD <property_name> ...: Defines a property of the model.
    • WITH TOPIC "" [AS TRIGGER]: Indicates this property’s value comes from another MQTT topic. If AS TRIGGER is present, updates on this topic cause the model to recompute.
    • WITH : Assigns a fixed constant value to the property.
    • WITH (expression): Defines a property’s value as an expression based on other properties, arithmetic, conditions, or timestamps.

4.2 Timestamps and Conditions

  • IF Conditions:

    ADD "message" WITH IF alarm == "true" THEN "all ok!" ELSE "message has an alarm 33"

  • Timestamp:

    ADD "timestamp" WITH TIMESTAMP "UTC"

    This can add a timestamp to your computed data in various formats ("UTC", "ISO", "UNIX-MS", or "UNIX").

5. Model Management Guidelines

Like rules, models can be added or removed dynamically using commands published to the $SYS/Coreflux/Command topic.

5.1 Add a Model: addModel <DEFINE MODEL code>

This command allows you to add a new model to the system. Example:

-addModel DEFINE MODEL LampEnergyCost WITH TOPIC "Coreflux/+/+/+/+/energy"
    ADD "total_energy" WITH TOPIC "shellies/+/+/+/+/device/energy" AS TRIGGER
    ADD "energy_price" WITH 3
    ADD "cost" WITH (total_energy * energy_price)

In this example:

  • The model is named LampEnergyCost.
  • The output base topic is Coreflux/+/+/+/+/energy.
  • total_energy comes from shellies/+/+/+/+/device/energy and triggers computations.
  • energy_price is a constant 3.
  • cost is computed as (total_energy * energy_price).

Whenever a shellies/.../device/energy message arrives, the model computes outputs and publishes to Coreflux/.../energy/total_energy, Coreflux/.../energy/energy_price, and Coreflux/.../energy/cost.

Another example:

-addModel DEFINE MODEL LampEnergyCostFixed WITH TOPIC "shellies/Coreflux/Students/Lamp/Lamp1/costs"
    ADD "total_energy" WITH TOPIC "shellies/Coreflux/Students/Lamp/Lamp1/device/energy" AS TRIGGER
    ADD "energy_price" WITH 2
    ADD "cost" WITH (total_energy * energy_price)

Here, the model is fixed to a specific device path without wildcards, outputting computed values to shellies/Coreflux/Students/Lamp/Lamp1/costs/....

5.2 Remove a Model: removeModel <model_name>

This command removes an existing model by specifying its name. Example:

-removeModel LampEnergyCost

In this example, the model LampEnergyCost is removed from the system. This stops the model from processing future messages and publishing outputs.

6. Additional Examples

6.1 UNS Style Models

DEFINE MODEL GenericEnergyCost WITH TOPIC "Coreflux/+/+/+/+/energy"
    ADD "total_energy" WITH TOPIC "shellies/+/+/+/+/device/energy" AS TRIGGER
    ADD "energy_price" WITH 3
    ADD "cost" WITH (total_energy * energy_price)

For any device matching the shellies/.../device/energy pattern, this model will process data and publish to Coreflux/.../energy/....

6.2 Direct, Singleton Model

DEFINE MODEL SpecificMachineStopOrder WITH TOPIC "company/factory/department/machine/stopOrder"

If a JSON payload like:

{
  "reason": 42,
  "stop": true,
  "time": "2024-12-11T15:12:54Z"
}

arrives at company/factory/department/machine/stopOrder, the model will break it down into:

  • company/factory/department/machine/stopOrder/reason -> 42
  • company/factory/department/machine/stopOrder/stop -> true
  • company/factory/department/machine/stopOrder/time -> "2024-12-11T15:12:54Z"

(Note: If you want to define additional properties or triggers, you can ADD them similarly.)

6.3 Conditional Message Models

DEFINE MODEL AlertMessage2 WITH TOPIC "Company2/+/+/+/AlarmMessage"
    ADD "alarm" WITH TOPIC "shellies2/+/+/+/device/alarm" AS TRIGGER
    ADD "message" WITH IF alarm == "true" THEN "all ok!" ELSE "message has an alarm 33"
    ADD "timestamp" WITH TIMESTAMP "UTC"

When alarm triggers, the model publishes a message to Company2/.../AlarmMessage/... including a processed message and a timestamp.

6.4 Counters and Running Totals

DEFINE MODEL ProductionCounterModel WITH TOPIC "machine/productionCounter"
    ADD "Value" WITH TOPIC "machine/signal/countPart" AS TRIGGER
    ADD "Counter" WITH (Counter + Value)

Each time machine/signal/countPart receives a new number, the model adds it to the Counter property, creating a running total published under machine/productionCounter/Counter.