LoT Concepts

Why Paradigms Matter

LoT (Language of Things) combines two programming approaches—imperative and declarative—each optimized for different tasks. Understanding when to use each one makes your code cleaner, more maintainable, and easier to debug.

Like a restaurant kitchen. Imperative commands are the chef shouting “Plate this now!” (immediate actions). Declarative definitions are the recipes and menu (structures that define how things work when triggered).

When to Use This

You’re learning LoT and want to understand the core paradigms and building blocks
You need a naming and conventions reference for entities, variables, and topics
You’re designing a topic hierarchy for a new or growing system
You want proven code patterns to follow — and anti-patterns to avoid

In This Page

Two Ways to Write LoT — Imperative commands vs. declarative definitions
The Four Building Blocks — Actions, Models, Routes, and Rules
How They Work Together — A combined example
Naming Conventions — How to name every LoT entity
Topic Hierarchy Design — Structuring your MQTT topic tree
Code Patterns — Proven templates for common LoT logic
Anti-Patterns — Common mistakes and how to avoid them

Two Ways to Write LoT

LoT uses two syntax styles based on what you’re doing:

Imperative Commands
Declarative Definitions

Direct actions executed immediately by the broker. Use these inside Actions to do things right now.

PUBLISH TOPIC "alerts/temperature" WITH PAYLOAD
SET "counter" WITH (GET TOPIC "stats/count" + 1)
KEEP TOPIC "data/cached" WITH PAYLOAD
CALL ACTION "ProcessData"
SET "host" WITH (GET ENV "DB_HOST")
SET "pass" WITH (GET SECRET "DB_PASSWORD")

Command	What it does
`PUBLISH`	Send a message to a topic
`SET`	Store a value in a variable
`GET`	Retrieve a value from a topic or variable
`GET ENV`	Read an environment variable
`GET SECRET`	Read an encrypted secret
`KEEP`	Publish and retain a message
`CALL`	Execute another Action

Blueprints that describe what should exist and when it activates. These define the structure of your automation.

DEFINE ACTION MonitorTemperature
ON TOPIC "sensors/temp" DO
    PUBLISH TOPIC "processed/temp" WITH PAYLOAD

DEFINE MODEL SensorReading WITH TOPIC "sensors/formatted"
    ADD STRING "sensor_id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw" AS TRIGGER

Keyword	What it defines
`DEFINE ACTION`	Executable logic with a trigger
`DEFINE MODEL`	Data schema for structured messages
`DEFINE ROUTE`	External system integration
`DEFINE RULE`	Access control policy

When to Use Each Paradigm

Scenario	Paradigm	Example
Publish a message now	Imperative	`PUBLISH TOPIC "status" WITH "online"`
React when data arrives	Declarative	`DEFINE ACTION ... ON TOPIC "input" DO`
Store a calculation result	Imperative	`SET "total" WITH ({a} + {b})`
Structure JSON output	Declarative	`DEFINE MODEL ... ADD STRING "id"`
Connect to a database	Declarative	`DEFINE ROUTE ... TO POSTGRESQL`
Read configuration	Imperative	`GET ENV "DB_HOST"`
Read credentials	Imperative	`GET SECRET "DB_PASSWORD"`
Forward data in a loop	Imperative	`PUBLISH TOPIC "out" WITH PAYLOAD`

The Four Building Blocks

Everything in LoT is built from four declarative constructs:

Construct	Purpose	Trigger Types
Actions	Execute logic when events occur	Time, Topic, System events, Manual
Models	Structure MQTT data into JSON schemas	Topic values, Action calls
Routes	Connect to external systems	Topic patterns
Rules	Control who can publish/subscribe	Client identity, Topic patterns

Actions in Detail

Actions contain your automation logic. They run when triggered:

Trigger	Syntax	Use Case
Time-based	`ON EVERY 5 SECONDS`	Heartbeats, polling, scheduled tasks
Topic-based	`ON TOPIC "sensors/+"`	React to incoming data
Callable	No trigger clause	Utility functions, subroutines
System	`ON START`, `ON STOP`	Initialization, cleanup

Inside an Action, you use imperative commands like PUBLISH, SET, IF/THEN, and CALL.

Models in Detail

Models define JSON structures that auto-publish when their trigger fields update:

Field Type	Purpose
`STRING`, `INT`, `DOUBLE`, `BOOL`	Typed data fields
`AS TRIGGER`	Field that activates the model when it changes
`FROM`	Inherit fields from another model

Models eliminate manual JSON formatting—define the schema once, and data flows automatically.

Routes in Detail

Routes connect your MQTT infrastructure to external systems:

Category	Examples
Data Storage	PostgreSQL, MongoDB, CrateDB, OpenSearch
Data Pipeline	MQTT bridges, email, HTTP webhooks
Industrial	OPC-UA, Modbus, Siemens S7, Allen-Bradley
System	Broker clustering, replication

Routes are declarative—you define what to connect, and the broker handles the how.

Rules in Detail

Rules define access control at the broker level:

Control	Description
Publish permissions	Who can send messages to which topics
Subscribe permissions	Who can receive messages from which topics
Client identity	Match rules to specific clients or patterns

Rules enforce security policies without modifying your Actions or Models.

How They Work Together

A typical LoT solution combines all four building blocks:

-- 1. ROUTE: Connect to PostgreSQL
DEFINE ROUTE SensorDB TO POSTGRESQL
    CONNECTION "Host=db.local;Database=iot"
    TOPIC "sensors/#"

-- 2. MODEL: Structure incoming data
DEFINE MODEL SensorReading WITH TOPIC "sensors/formatted"
    ADD STRING "device_id" WITH TOPIC "sensors/id"
    ADD DOUBLE "temperature" WITH TOPIC "sensors/raw" AS TRIGGER

-- 3. ACTION: Process and alert
DEFINE ACTION TemperatureAlert
ON TOPIC "sensors/formatted" DO
    SET "temp" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    IF {temp} > 80 THEN
        PUBLISH TOPIC "alerts/high_temp" WITH PAYLOAD

-- 4. RULE: Restrict who can publish alerts
DEFINE RULE AlertAccess
    DENY PUBLISH "alerts/#" FOR ALL
    ALLOW PUBLISH "alerts/#" FOR "system-*"

Step	What Happens
1	Route stores all `sensors/#` data to PostgreSQL
2	Model transforms raw data into structured JSON
3	Action checks thresholds and publishes alerts
4	Rule ensures only system clients can write alerts

Naming Conventions

Consistent naming is the single most impactful practice for maintainable LoT systems. These conventions apply to all LoT entities.

Entity Names

All LoT entities use PascalCase. Names should be descriptive and purpose-driven.

Entity	Convention	Good Examples	Bad Examples
Actions	PascalCase, verb-first	`ProcessTemperature`, `MonitorPressure`, `SendDailyReport`	`temp_process`, `action1`, `myAction`
Models	PascalCase, noun-based	`SensorReading`, `EquipmentStatus`, `ProductionRecord`	`sensor_model`, `Model1`, `data`
Rules	PascalCase, descriptive scope	`AllowAdminActions`, `ProtectSysTopics`, `RestrictDevicePublish`	`Rule1`, `myRule`, `newRule`
Routes	PascalCase, destination-based	`CloudBridge`, `SensorDatabase`, `AlertEmail`	`route1`, `my_route`, `dbRoute`
Callable Actions	PascalCase, function-like	`CalculateAverage`, `ConvertCelsiusToFahrenheit`	`calc`, `helper`, `util`

Variable Names

Variables use snake_case inside double quotes for SET declarations, and curly braces for references.

DEFINE ACTION ProcessSensorData
ON TOPIC "sensors/+/raw" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "raw_value" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    SET "converted_value" WITH ({raw_value} * 1.8 + 32)
    PUBLISH TOPIC "processed/" + {sensor_id} + "/fahrenheit" WITH {converted_value}

Context	Convention	Examples
Declaration (`SET`)	`snake_case` in double quotes	`"sensor_id"`, `"raw_value"`, `"cycle_time"`
Reference	Curly braces	`{sensor_id}`, `{raw_value}`, `{cycle_time}`
Model fields	`snake_case` in double quotes	`"equipment_id"`, `"runtime_hours"`, `"last_update"`
Action inputs	`snake_case` after keyword	`INPUT value AS DOUBLE`, `INPUT threshold AS DOUBLE`

Topic Names

Topics use lowercase with forward-slash separators. Multi-word segments use snake_case. Whenever possible, follow a Unified Namespace (UNS) format for topic naming. This enables not only proper readability but also scalability of systems.

Pattern	Example	Use Case
`domain/entity/attribute`	`sensors/temperature/value`	General data
`domain/instance/attribute`	`sensors/temp001/raw`	Instance-specific data
`domain/category/instance`	`alerts/critical/pump03`	Categorized events
Prefixed namespaces	`processed/`, `alerts/`, `config/`, `cache/`, `state/`, `system/`	Functional separation

Topic Hierarchy Design

A well-designed topic tree is the most critical architectural decision in a LoT system. Every entity — Actions, Models, Rules, and Routes — communicates through topics. A clean hierarchy makes the entire system easier to build, debug, and extend.

Recommended Namespace Structure

Organize topics into functional namespaces that reflect the data lifecycle:

Namespace	Purpose	Example Topics
`sensors/`	Raw incoming sensor data	`sensors/temp001/raw`, `sensors/+/temperature`
`processed/`	Transformed or enriched data	`processed/temp001/fahrenheit`, `processed/+/status`
`alerts/`	Threshold violations and notifications	`alerts/critical/pump03`, `alerts/+/temperature`
`config/`	Configuration values read by Actions	`config/setpoint`, `config/max_temperature`
`state/`	Internal persistent state (used with `KEEP`)	`state/counter`, `state/last_run`
`cache/`	Cached values for quick reference	`cache/temp001/last_reading`
`system/`	Heartbeats, health checks, diagnostics	`system/heartbeat`, `system/status`
`commands/`	Inbound instructions from external systems	`commands/devices/+/restart`

Wildcard Guidelines

Wildcard	Meaning	Where to Use
`+`	Matches exactly one level	Action triggers, Model topics, Route mappings
`#`	Matches one or more levels	Route mappings, Rule topic patterns, broad subscriptions

Use + in Actions and Models for precise instance matching. Use # in Routes and Rules for broad coverage. A wildcard-triggered Action like ON TOPIC "sensors/+/raw" automatically resolves + in GET TOPIC and PUBLISH TOPIC to the same matched value — this is called wildcard context inheritance:

DEFINE ACTION ProcessWithContext
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "humidity" WITH (GET TOPIC "sensors/+/humidity" AS DOUBLE)
    PUBLISH TOPIC "processed/" + {sensor_id} + "/combined" WITH {humidity}

In this example, if triggered by sensors/temp001/temperature, the GET TOPIC reads from sensors/temp001/humidity — the wildcard resolves to the same instance.

Code Patterns

Proven templates and patterns for common LoT logic. Each pattern addresses a specific architectural need — use them as starting points for your own implementations.

Actions: Single Responsibility

Each Action should do one thing well. Break complex logic into callable Actions with INPUT/OUTPUT:

Good: Modular
Bad: Monolithic

Separate reusable logic into callable Actions, then compose them in a main Action:

DEFINE ACTION ConvertCelsiusToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit

DEFINE ACTION ProcessTemperatureReading
ON TOPIC "sensors/+/celsius" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp_c" WITH PAYLOAD AS DOUBLE

    CALL ACTION ConvertCelsiusToFahrenheit
        WITH celsius = {temp_c}
        RETURN temp_f

    PUBLISH TOPIC "sensors/" + {sensor_id} + "/fahrenheit" WITH {temp_f}

All logic crammed into one Action, no reuse:

DEFINE ACTION DoEverything
ON TOPIC "sensors/+/celsius" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp_c" WITH PAYLOAD AS DOUBLE
    SET "temp_f" WITH ({temp_c} * 9 / 5 + 32)
    SET "temp_k" WITH ({temp_c} + 273.15)
    SET "max" WITH (GET TOPIC "config/max_temperature" AS DOUBLE)
    SET "pct" WITH ({temp_c} / {max} * 100)
    IF {temp_c} > {max} THEN
        PUBLISH TOPIC "alerts/" + {sensor_id} WITH "High"
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/kelvin" WITH {temp_k}
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/capacity" WITH {pct}

Actions: State Management

Use KEEP TOPIC for internal persistent state and PUBLISH TOPIC for external broadcast. Never use PUBLISH for values only your system reads:

DEFINE ACTION PersistentCounter
ON EVERY 10 SECONDS DO
    SET "current" WITH (GET TOPIC "state/counter")
    IF {current} == EMPTY THEN
        KEEP TOPIC "state/counter" WITH 1
    ELSE
        KEEP TOPIC "state/counter" WITH ({current} + 1)
    PUBLISH TOPIC "stats/count" WITH (GET TOPIC "state/counter")

Operation	Use When
`PUBLISH TOPIC`	Other systems or subscribers need to see the value
`KEEP TOPIC`	Only your own Actions read the value (internal state, caches, counters)

Models: Trigger Selection

Mark the primary data field as AS TRIGGER — never a timestamp or metadata field. The trigger determines when the model publishes, so it should fire when new meaningful data arrives:

DEFINE MODEL SensorReading WITH TOPIC "sensors/formatted/temperature"
    ADD STRING "sensor_id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw/temperature" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"

Use COLLAPSED models when you need full control over publishing timing and destination — the Action decides when and where to publish:

DEFINE MODEL AlarmRecord COLLAPSED
    ADD STRING "alarm_id"
    ADD STRING "equipment_id"
    ADD STRING "severity"
    ADD STRING "timestamp"

DEFINE ACTION ProcessAlarm
ON TOPIC "alarms/+/raw" DO
    SET "equip_id" WITH TOPIC POSITION 2
    PUBLISH MODEL AlarmRecord TO "alarms/structured/" + {equip_id} WITH
        alarm_id = (RANDOM UUID)
        equipment_id = {equip_id}
        severity = (GET JSON "severity" IN PAYLOAD AS STRING)
        timestamp = TIMESTAMP "UTC"

Models: Inheritance for Consistency

When you have a family of related data types, define a base COLLAPSED model and extend it:

DEFINE MODEL BaseAlert COLLAPSED
    ADD STRING "alert_id"
    ADD STRING "timestamp"
    ADD STRING "severity"
    ADD STRING "message"

DEFINE MODEL TemperatureAlert FROM BaseAlert
    ADD DOUBLE "temperature_value"
    ADD DOUBLE "threshold"
    ADD STRING "sensor_location"

DEFINE MODEL PressureAlert FROM BaseAlert
    ADD DOUBLE "pressure_value"
    ADD DOUBLE "max_safe_pressure"
    ADD STRING "system_affected"

Rules: Priority and Scope

Rules are evaluated by priority (lower number = higher priority). Structure them as specific deny rules first, then broader allow rules:

DEFINE RULE ProtectSysTopics WITH PRIORITY 10 FOR PublishSys
    IF USER IS "root" THEN
        ALLOW
    ELSE
        DENY

DEFINE RULE AllowDevicePublish WITH PRIORITY 50 FOR Publish TO TOPIC "sensors/#"
    IF USER HAS AllowedSensorPublish THEN
        ALLOW
    ELSE
        DENY

Practice	Guideline
Priority 1–20	Critical deny rules (system protection)
Priority 21–50	Specific allow rules (per-feature access)
Priority 51–100	General allow rules (broad access)
Condition style	Prefer `USER HAS <permission>` over `USER IS "<name>"` for maintainability

Routes: Clear Configuration

Name route mappings descriptively and group related mappings within a single route definition:

DEFINE ROUTE CloudSync WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeDevice-Factory1"
        WITH USE_TLS true
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "factory1/sensors/#"
        WITH DIRECTION "out"
    ADD MAPPING inboundCommands
        WITH SOURCE_TOPIC "local/commands/#"
        WITH DESTINATION_TOPIC "factory1/commands/#"
        WITH DIRECTION "in"

Anti-Patterns

These are the most common mistakes in LoT development. Avoid them whether you’re writing new code or reviewing existing output.

Anti-Pattern	Why It’s Bad	Do This Instead
Omitting type casts in math	Implicit type handling leads to silent errors	Always cast: `PAYLOAD AS DOUBLE`, `GET TOPIC ... AS DOUBLE`
Triggering models on timestamps	Timestamps update every tick — model fires constantly	Trigger on the primary data field: `AS TRIGGER` on value, not timestamp
Inconsistent naming across models	`sensorID` in one model, `sensor_id` in another	Standardize on `snake_case` for all field names
Using Python for native LoT tasks	Python adds overhead for simple publish/get/if operations	Use Python only for math libraries, ML, API calls, or complex parsing
Leaving `$SYS/#` topics unrestricted	System topics contain broker commands and sensitive data	Create a priority-10 Rule restricting `PublishSys` and `SubscribeSys`
Generic entity names	`Action1`, `Rule1`, `MyRoute` are meaningless in a system with 50 entities	Name by purpose: `MonitorPressure`, `ProtectSysTopics`, `SensorDatabase`
`PUBLISH` for internal state	Broadcasts data that only your own Actions need	Use `KEEP TOPIC` for internal state; `PUBLISH` for external subscribers
Monolithic Actions	One Action doing 15 things is hard to test and debug	Split into callable Actions with `INPUT`/`OUTPUT`

Quick Start

MQTT Broker

AI

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

Why Paradigms Matter

When to Use This

In This Page

Two Ways to Write LoT

When to Use Each Paradigm

The Four Building Blocks

How They Work Together

Naming Conventions

Entity Names

Variable Names

Topic Names

Topic Hierarchy Design

Recommended Namespace Structure

Wildcard Guidelines

Code Patterns

Actions: Single Responsibility

Actions: State Management

Models: Trigger Selection

Models: Inheritance for Consistency

Rules: Priority and Scope

Routes: Clear Configuration

Anti-Patterns

Next Steps

Write Your First Action

AI-Assisted Development

Quick Start

MQTT Broker

AI

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

​Why Paradigms Matter

​When to Use This

​In This Page

​Two Ways to Write LoT

​When to Use Each Paradigm

​The Four Building Blocks

​How They Work Together

​Naming Conventions

​Entity Names

​Variable Names

​Topic Names

​Topic Hierarchy Design

​Recommended Namespace Structure

​Wildcard Guidelines

​Code Patterns

​Actions: Single Responsibility

​Actions: State Management

​Models: Trigger Selection

​Models: Inheritance for Consistency

​Rules: Priority and Scope

​Routes: Clear Configuration

​Anti-Patterns

​Next Steps

Write Your First Action

AI-Assisted Development

Why Paradigms Matter

When to Use This

In This Page

Two Ways to Write LoT

When to Use Each Paradigm

The Four Building Blocks

How They Work Together

Naming Conventions

Entity Names

Variable Names

Topic Names

Topic Hierarchy Design

Recommended Namespace Structure

Wildcard Guidelines

Code Patterns

Actions: Single Responsibility

Actions: State Management

Models: Trigger Selection

Models: Inheritance for Consistency

Rules: Priority and Scope

Routes: Clear Configuration

Anti-Patterns

Next Steps