How to Use a LoT Notebook

VS Code with a LoT notebook open showing markdown and LoT code cells, Coreflux Explorer and project tree on the left, Data Viewer below, and MQTT connection in the status bar — LoT Notebook workspace in VS Code: editor, Coreflux Explorer, Project, and Data Viewer

The Notebook Workflow

LoT Notebooks combine Documentation in Markdown and LoT code in a single file, so you can both run your code and keep your documentation together, using the notebook as living documentation for your project.

Picture a smart kitchen: Markdown is the recipe on the page, each LoT code cell is how you run each step of the recipe, and the Data Viewer shows you the results of each step.

Install and connect

Install the extension

Animated walkthrough: VS Code Extensions view, search for coreflux, install Coreflux LoT, Coreflux icon appears in the Activity Bar — Extensions marketplace: search for Coreflux and install LoT Notebooks

Open VS Code.
Open the Extensions view in the sidebar (or use the shortcut Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS).
Search for LoT Notebooks by Coreflux and install it.

Connect to the broker

VS Code: connect to MQTT broker via LoT extension; status bar shows MQTT connected — Connect to the broker: pick credentials or connect from the Data Viewer

Click the MQTT connection status in the bottom-left of VS Code, or click Connect to Broker in the Data Viewer (Coreflux sidebar).
Enter your broker URL, username, and password.

Setting	Example (local defaults)
URL	`mqtt://localhost:1883`
Username	`root`
Password	`coreflux` (change immediately in production)

When you are connected, the status bar shows a green MQTT: Connected. If any issues occur, the status bar will become red.

The extension securely stores your credentials. You only need to configure them once per workspace.

Create a new project

Animated walkthrough: creating a new .lotnb file from the Coreflux PROJECT section in VS Code — Creating a new LoT Notebook from the Coreflux PROJECT view

In the Activity Bar, open the Coreflux view. Under PROJECT, use New File to create a notebook and save it in your workspace (use New Folder first if you want a dedicated project folder).
In the notebook, add Markdown and LoT cells from the toolbar as needed.

Add LoT code to a LoT Notebook

Animated walkthrough: insert a code cell in a LoT Notebook and add LoT definition text in VS Code — Insert a LoT code cell and add LoT in the notebook editor

Open your LoT Notebook in VS Code.
From the notebook toolbar, add a code cell.
Type or paste your LoT code (DEFINE ACTION, DEFINE MODEL, and so on). For a first example, use the code below.

DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"

What type of cells you can add to LoT Notebooks

LoT Notebooks support three types of cells, each with different behavior:

Markdown Cells - Documentation

LoT Notebook markdown cell showing a heading and body text with the cell toolbar for formatting and actions — Markdown cell with rich text and the formatting toolbar

Markdown cells are for documentation only—they don’t execute. Use them to:

Explain what your code does and why
Document configuration requirements
Add diagrams, tables, and formatted text
Create section headers and navigation

LoT Code Cells - Runnable Logic

LoT Notebook LoT cell with TemperatureSimulator action, run button, and status bar showing Upload to broker and LOT cell type — LoT code cell: syntax highlighting, sync status and upload to broker buttons

LoT cells contain executable LoT (Language of Things) code. When you run a LoT cell:

The extension parses your code
Sends it to the connected broker via MQTT
The broker compiles and registers the definition
You receive confirmation or error feedback

For what LoT is, how it fits the broker, and more examples, see Introduction to LoT.

Validate without deploying

Validate in the cell status bar, or LOT Notebook: Validate LOT Cell and Validate LOT Notebook in the Command Palette, asks the broker to check the code without deploying it. The broker’s summary and each diagnostic (severity, code, line, and message) appear under the cell and in Problems with source Coreflux. Notebook validation includes Python cells. Diagnostics clear when you edit the cell. Needs a broker newer than 2.14.

Disable an entity

Action, connector, and agent cells have an Enabled / Disabled toggle in the cell status bar. It adds DISABLE true on the line after DEFINE, or removes it; a DISABLE inside a comment is left alone. When you’re connected, the cell is uploaded right away; offline, upload it once you connect. The broker keeps a disabled entity defined, but doesn’t run it. A broker without DISABLE support leaves the cell unchanged. The same toggle is LOT Notebook: Enable / Disable LOT Cell (DISABLE). See Disable and Enable.

THING cells

Running a cell with DEFINE THING blocks sends them as typed, with every template they use from the workspace, as one -addThing. The broker expands them; the extension doesn’t.

Every run checks first with -addThing --dryRun. Problems appear on the cell at the line of the THING source.
When a template change would redeploy other root Things, the extension lists them and asks first.
The cell output shows the broker’s plan per root: add, update, adopt, remove, or unchanged for each child.
Remove Thing from Broker sends -removeThing. The broker refuses to remove a template that’s in use.
A cell in the older THING syntax offers a quick fix that adds TEMPLATE and rewrites {p} to {{p}}. You can Apply All, or Review in Refactor Preview first.
On a broker without THING support, the cell says so and deploys nothing.

The Coreflux Explorer and the Entities panel show each root Thing with its state, its instances, and their read-only children. A Thing that no workspace notebook defines is marked not in workspace.

Agent cells

A DEFINE AGENT cell deploys with -addAgent and is removed with -removeAgent. The extension checks the agent like the broker does: a missing USES LLM CONNECTOR (USES LLM ROUTE is still accepted) or DEFAULT_USER, unknown clauses or tools, and an ADD TOOL without its TOPICS, TARGET, or LEVEL "write" are errors. Agents on the broker appear in the Coreflux Explorer and under Agents in the Entities panel. Agent, Thing, rule, connector, and model checks follow the broker. A connector key such as SUBJECT, and a mixed-case name, are not reported as unknown keywords.

DEFINE AGENT NightShift
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_mqtt"
        WITH TOPICS "plant/#"

See LoT Agents.

Panel cells

A DEFINE PANEL or DEFINE VISU cell is checked with the broker’s panel parser: component types, SET, BIND, ON … DO, AT, ADD THRESHOLD, and MAPPING. A typo stays an error. Where the broker falls back, the cell shows a warning. Highlighting, hover, and completions cover the panel keywords, and the DEFINE PANEL snippet inserts a starter panel. Running the cell deploys with -addVisu (the same command as -addPanel). Removing it sends -removeVisu. A Thing’s WITH PANEL body is checked the same way. DEFINE THEME and THEME_VARIANT are recognized. The cell status bar offers Open in Coreflux HUB to view the rendered panel, and a successful upload suggests opening Dashboards there. See Defining a Panel.

Python Cells - Advanced Logic

LoT Notebook Python cell with Script Name header, function definitions, run button, and Python label in the status bar — Python cell with syntax highlighting, sync status and upload to broker buttons

Python cells contain scripts that run inside the broker when called from LoT Actions. The broker’s Python runtime executes your functions.

# Script Name: DataProcessor
def calculate_average(values):
    """Calculate average from a list of numbers"""
    if not values:
        return 0
    return sum(values) / len(values)

def format_alert(sensor_id, value, threshold):
    """Generate formatted alert message"""
    return f"ALERT: Sensor {sensor_id} exceeded {threshold} with value {value}"

Python scripts require a specific format with # Script Name: YourScriptName as the first line. Without this header, the script won’t be recognized.

Running LoT

Animated walkthrough: Run on a LoT notebook cell to deploy the definition to the connected Coreflux broker — Deploying a LoT or Python code from the notebook to the broker

When you click the Run button on a cell, the Extension builds your code, checks for errors and deploys to the broker. If successful, a simple Green response will appear. If any error is found, the code is not deployed and a error message will appear with the error details.

What else you can do with the LoT extension

Animated walkthrough of the LoT Data Viewer in VS Code: subscribing to topics and viewing live MQTT traffic — Data Viewer basics: subscribe to topics and watch live MQTT data

Use the Coreflux view (Activity Bar) for broker connection, entities, secrets, license, clients, and live MQTT—without a separate client for most tasks.

Capability	Why it helps
See what is running in the Broker	See what Actions, Models, Connectors, and Rules the broker actually has after a deploy.
Remove LoT code	On Coreflux Explorer, remove one or more LoT entities.
Manage secrets and variables	Configure secrets and variables on the broker, to manage secure credentials. Open Secrets & Variables from Broker Management
See license usage	Spot license limits when deploy fails—before you debug LoT as a syntax issue.
Activate a license	Activate, install, enroll, and refresh from the License tab. See License tab
Configure the MCP server	Turn on the broker’s MCP server, manage its tokens, and install it into AI clients. See MCP Server tab
See connected clients	See who is connected; useful when a device or app should be online but is not.
MQTT Data Viewer	Live topics and payloads in the Data Viewer.
Execution Trace	For a LoT cell, see it’s execution history and which topics and variables that run touched.

For more on the Data Viewer, replay, formatters, and trace, see How to Debug in LoT Notebooks.

License tab

Open License Management from Broker Management. The tab shows the plan, expiry, features, and usage from $SYS/Coreflux/License, and offers these actions:

Action	What to enter	Broker command
Activate	An activation code (`CFLX-…`)	`-activateLicense`
Install	The signed license text, pasted or from a file	`-loadLicense`
Enroll	An organization enrollment token (`et_…`)	`-enroll`
Refresh	Nothing: forces a lease refresh	`-refreshLicense`

You can also load a license file that’s already on the broker host by its path. See Licensing and Enrollment.

MCP Server tab

Coreflux: Configure MCP Server opens the broker’s built-in MCP server settings, the same ones as the HUB MCP tab:

Server — Enabled, status (Listening, Disabled, or Pending restart), the endpoint URL with Copy, port, bind IP, and endpoint path. Saved changes apply when the broker restarts.
Tools — Expose all tools, or pick an allow-list from the broker’s catalog.
Tokens — List, create, and revoke tokens (-listMcpTokens, -createMcpToken, -revokeMcpToken). A new token is shown once.

Install MCP server creates a token for the broker user you pick and writes the endpoint and token into each client you tick: Cursor, VS Code, Claude Code, or Claude Desktop (through npx mcp-remote). Existing config files are edited in place, keeping comments and other servers. A workspace install also adds the config file to .gitignore, so the token isn’t committed. See MCP Server.

Develop LoT Notebooks with AI

Animated walkthrough: VS Code with a LoT notebook open and GitHub Copilot chat focused on a notebook cell — GitHub Copilot with a LoT Notebook: chat in context of the open notebook and cells

Alongside the extension, you can develop with AI using Copilot, just like any programming language. For better results, you can add the Coreflux MCP server to the agent, so it can read official docs, and add AGENTS.md file for LoT coding practices, so it works like a LoT expert. To connect your AI client to the broker itself, use Install MCP server. Nothing is installed automatically on startup. Install Agent Skills… lets you pick which skills to install and the target folders: .agents, .claude, .cursor, or .github skills folders, in the workspace or in your home folder. The 11 bundled skills come from the public coreflux-skills repository. See Agent Skills (broker 2.22 or later) for the skill list and other ways to install them. Older copies from previous versions are offered to move to the trash. To for more details on how to use AI with LoT, check this page: Developing with LoT Using AI.

Version control with Git

VS Code Source Control showing pending changes across .lotnb notebooks, docker-compose.yml, markdown, and editor config files in the same repo — Source Control: Git tracks the whole workspace, not just LoT notebooks

Use Git on your workspace folder like any project: commit .lotnb files aswell as any other files, like documentation, Docker files and supporting files.

Best Practices

Organize with Markdown

Use markdown cells liberally to explain your code. Future you (and teammates) will appreciate the context.

One Definition Per Cell

Keep each Action, Model, or Connector in its own cell. This makes debugging easier and allows selective execution.

Test Incrementally

Run cells one at a time when developing. This helps isolate issues and understand system behavior.

Use Descriptive Names

Name your Actions, Models, and Connectors clearly. They appear in the broker’s entity lists and should be self-explanatory.

Troubleshooting

Cell won't run?

Check that you’re connected to the broker (look for connection status in status bar)
Verify your credentials are correct
Ensure the broker is running and accessible

LoT not deployed — license limits?

If running a cell shows an error and the broker rejects the definition because you have reached a license limit (for example on actions, connectors, or another licensed resource), deployment stops and the message under the cell should describe the limit. Open the Coreflux view in the Activity Bar and check the Coreflux Explorer section for your license status and usage so you can see what is capped. To raise the plan, see Licensing and Enrollment.

Python script not recognized?

Confirm the first line is # Script Name: YourScriptName
Check for syntax errors in the Python code
Ensure function names match what you’re calling from LoT

Entity not appearing after deployment?

Check the output for error messages
Verify no syntax errors in your LoT code
Use the Coreflux Entities panel to refresh the list

Next Steps

Debug in VS Code

Use cell output, Coreflux Entities, and live MQTT values to fix issues.

Explore Tutorials

Work through hands-on notebooks covering Actions, Models, Connectors, and Python.

Extension Release Notes

See what shipped in each VS Code extension release.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

The Notebook Workflow

Install and connect

Create a new project

Add LoT code to a LoT Notebook

What type of cells you can add to LoT Notebooks

Markdown Cells - Documentation

LoT Code Cells - Runnable Logic

Validate without deploying

Disable an entity

THING cells

Agent cells

Panel cells

Python Cells - Advanced Logic

Running LoT

What else you can do with the LoT extension

License tab

MCP Server tab

Develop LoT Notebooks with AI

Version control with Git

Best Practices

Troubleshooting

Next Steps

Debug in VS Code

Explore Tutorials

Extension Release Notes

​The Notebook Workflow

​Install and connect

​Create a new project

​Add LoT code to a LoT Notebook

​What type of cells you can add to LoT Notebooks

​Markdown Cells - Documentation

​LoT Code Cells - Runnable Logic

​Validate without deploying

​Disable an entity

​THING cells

​Agent cells

​Panel cells

​Python Cells - Advanced Logic

​Running LoT

​What else you can do with the LoT extension

​License tab

​MCP Server tab

​Develop LoT Notebooks with AI

​Version control with Git

​Best Practices

​Troubleshooting

​Next Steps

Debug in VS Code

Explore Tutorials

Extension Release Notes

The Notebook Workflow

Install and connect

Create a new project

Add LoT code to a LoT Notebook

What type of cells you can add to LoT Notebooks

Markdown Cells - Documentation

LoT Code Cells - Runnable Logic

Validate without deploying

Disable an entity

THING cells

Agent cells

Panel cells

Python Cells - Advanced Logic

Running LoT

What else you can do with the LoT extension

License tab

MCP Server tab

Develop LoT Notebooks with AI

Version control with Git

Best Practices

Troubleshooting

Next Steps