> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Things Overview

> Group the connectors, models, agents, actions, rules and panels of one asset under a single DEFINE THING (preview)

Preview

> [!WARNING]
>
> `DEFINE THING` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

## What a Thing is

A **Thing** groups everything that belongs to one asset (a pump, a PLC, a press, a line, a site) under one name: its connectors, models, agents, actions, rules and panels.

You describe the asset once as a **template**, then deploy it as many times as you need from a **root**. The broker expands each root into ordinary `DEFINE` declarations, called its **children**, deploys them, and keeps owning them.

* **One unit**: a root and all its children deploy together or not at all. If a step fails, every child is rolled back.
* **Live templates**: editing a template redeploys every root that uses it, and only the children whose code changed.
* **Cascading removal**: removing a root removes its children in reverse deploy order.
* **Protected children**: a child can only be changed through its Thing. A direct add or remove is refused.
* **Dry run**: `-addThing --dryRun` returns the full plan and each child's expanded LoT, and changes nothing.
* **Recursive**: templates can use other templates to any depth (site → line → cell → device).

## A first Thing

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE TempSensor
    WITH PARAM limit 80
    WITH MODEL Reading WITH TOPIC "{{path}}/reading"
        ADD DOUBLE "temperature" WITH TOPIC "{{path}}/temp" AS TRIGGER
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION Overheat
    ON TOPIC "{{path}}/temp" DO
        SET "temp" WITH PAYLOAD AS DOUBLE
        IF {temp} > {{limit}} THEN
            PUBLISH TOPIC "{{path}}/alarm" WITH "overheat " + {temp}

DEFINE THING Oven
    WITH THING inlet OF TempSensor
    WITH THING outlet OF TempSensor
        WITH PARAM limit 120
```

Send both blocks in one `-addThing` command to `$SYS/Coreflux/Command`. `TempSensor` is a template and deploys nothing. `Oven` is a root and deploys four children:

| Child | Kind | Resolved |
| - | - | - |
| `Oven_inlet_Reading` | MODEL | topic `Oven/inlet/reading` |
| `Oven_outlet_Reading` | MODEL | topic `Oven/outlet/reading` |
| `Oven_inlet_Overheat` | ACTION | fires on `Oven/inlet/temp`, alarms above 80 |
| `Oven_outlet_Overheat` | ACTION | fires on `Oven/outlet/temp`, alarms above 120 |

`{{path}}` and `{{limit}}` are filled in when the broker expands the Thing. `{temp}` is an action variable: single braces always belong to the runtime and are never touched.

## When to use a Thing

| Use a Thing when | Use standalone definitions when |
| - | - |
| The same asset repeats (10 pumps, 3 lines) | Each entity is one of a kind |
| Several entities must deploy and be removed together | Entities have independent lifecycles |
| You want one place to change an asset's logic | A quick test or a single action |

## Managing Things

| Command | Does |
| - | - |
| `-addThing <DEFINE THING …>` | Adds or updates every Thing in the payload as one unit |
| `-addThing --dryRun <DEFINE THING …>` | Returns the plan, each child's expanded code and every diagnostic. Changes nothing |
| `-removeThing <name>` | Removes a root and its children, or a template no Thing uses |
| `-listThings` | Lists every Thing with its kind (`root` or `template`), template, users and child count |

Every Thing is published retained on `$SYS/Coreflux/Things/<name>` (the source), `…/tree` (the expanded instance tree) and, for roots, `…/status` (`ok`, `degraded` or `error`, from the children's health). Children keep their own topics.

## Next steps

> **[Thing Syntax](/latest/lot-language/things/syntax)**
>
> Templates, clauses, params, names, references and permissions.

> **[Agents Overview](/latest/lot-language/agents/overview)**
>
> Agents can be clauses of a Thing, with one per asset.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.