Config as Code (Lox Logic)

Write Miniserver logic as text, review it in a pull request, deploy it verified.

Table of contents

  1. How it works
  2. The language in one example
    1. Who may open a door
    2. Switching times and app switches
    3. Push notifications
  3. Set up a project
  4. The edit loop
  5. Deploy with lox config push
  6. When someone else changed the config
  7. Tests, CI and editors
  8. Reference

How it works

A Miniserver’s logic lives in one .Loxone XML file that only Loxone Config can edit. lox logic runs the Lox Logic toolchain, which treats it like Terraform treats infrastructure:

   
Module (*.loxl) Your source: the blocks, wires and parameters you manage
Base (.Loxone) The config the Miniserver runs now (a download)
Lockfile (*.lock.json) Pins every UUID the compiler created, so the next compile changes only what you changed
Out (.Loxone) Base + module, written exactly as Loxone Config would have drawn it

You manage only the logic you choose. Hardware, rooms, visualization, users and everyone else’s logic pass through byte for byte. Nothing in lox logic talks to the Miniserver. lox config push does the transport.

lox logic … and the standalone loxl … binary are the same CLI, so Lox Logic’s docs apply word for word. lox logic help lists the commands, and lox logic <command> --help shows one command’s flags.

The language in one example

page "Beschattung"

let temp_schwelle = 28

extern aussentemp = VirtualIn(iname: "VI1")          # owned by Loxone Config
extern sonne      = VirtualIn(iname: "VI3")
extern jal_sued   = AutoJalousie(title: "Beschattung Süd")

temp_hoch = GreaterEqual("Temp über 28", In1: aussentemp, In2: temp_schwelle)

jal_sued.AutoShade <- temp_hoch and sonne            # a wire; the `and` becomes an And block
jal_sued.TargetPos = 70                              # a parameter
  • extern names an object Loxone Config owns, matched by uuid, iname or title. You can wire to it, not create it. A title that repeats can be narrowed by room:, category: or device: (the hardware serial of the Extension or Tree device it hangs off).
  • A plain declaration (temp_hoch = GreaterEqual(…)) is a block the compiler owns.
  • page "Beschattung" puts the blocks that follow on that page. page "Küche Logik" (room: "Küche") creates the page if the config has none of that title, like “Neue Seite” in Loxone Config.
  • <- draws a wire, = sets a parameter. Expressions (and, >=, / 1000) compile to real blocks, units read as written (Time: 30min, 70%), and template … end stamps out repeated rules.

Who may open a door

Access rights on an NFC Code Touch can live in source too. An access set lists who may open, each user or group by its title with an access schedule, and a claim gives it to a Code Touch:

extern haustuer = NfcCodeTouch(uuid: "…")
extern garage = NfcCodeTouch(uuid: "…")

access bewohner
	user "alice": "Always"
	group "Residents": "Workdays"
end

haustuer.access = bewohner
garage.access = bewohner                 # one set, several doors

The claim owns that Code Touch’s access: whoever it leaves out loses the right on the next push. Users, groups, schedules, NFC tags and codes are still created in Loxone Config or the app. A title the config doesn’t have stops the compile. lox logic adopt and lox logic decompile write the sets and claims for the rights the config has, and lox logic lint names users whose tag or code opens no Code Touch.

Switching times and app switches

A schedule is a DayTimer’s week in source. A claim writes it onto a timer, extern or managed:

schedule abendlicht
	weekdays 06:00-07:30, 17:00-22:30
	weekend 08:00-23:00
	holiday vacation off
end

schaltuhr.schedule = abendlicht

party = VirtualIn("Partymodus")          # a new switch in the app, in the Virtual Inputs folder

The claim replaces the timer’s switching times and nothing else. Edits made in the app are overwritten on the next push, and removing the claim hands the times back to the app. A new VirtualIn gets the next free VI<n>.

Push notifications

A push notification is created in Loxone Config (Messages). The module names it and says when it fires, what it says and who gets it:

extern frost = Notification(title: "Frostwarnung Garten")

warn = OutputRefLM(mirrors: frost, AI: zu_kalt.Q, On: "Frost im Garten", MinimumTime: 12h)

recipients familie
	user "alice"
end

frost.recipients = familie

On: is sent when AI turns on, Off: (optional) when it turns off, and MinimumTime: keeps the messages apart. recipients works like access: whoever it leaves out stops getting the notification. Members of Full access always get it.

The full language: language.md. Worked examples: crates/loxone-config/examples.

Set up a project

A directory with a lox.toml is a project: one Miniserver, one deployment target. Keep it in git.

mkdir haus && cd haus && git init
lox config download --extract --save-as base.zip     # → base.zip + base.Loxone
lox logic decompile base.Loxone | less                  # read-only view of every page
# lox.toml — paths are relative to this file
base   = "base.Loxone"       # the deployed config (required)
module = "pages"             # a .loxl file or a directory of them (required)
lock   = "logic.lock.json"    # default: logic.lock.json
out    = "out.Loxone"        # default: out.Loxone
serial = "504F94112233"      # goes into created UUIDs, and push checks it

Then start in one of two ways:

# Take over the existing blocks Lox Logic can manage (one file per page)
lox logic adopt base.Loxone --out-dir pages --out-lock logic.lock.json

# …or adopt one block, e.g. one you just drew in Loxone Config
lox logic adopt base.Loxone --uuid <uuid> --as stiegenlicht \
    --module pages --lock logic.lock.json

Or write a new page from scratch in pages/. Find UUIDs and names with lox config find and lox config wiring.

Only block types whose ports are verified can be managed. Anything else stays unmanaged (adopt says so with a warning) and keeps working, untouched, as part of the base.

The edit loop

lox logic check                          # parse + validate, errors with line numbers
lox logic fmt --write                    # canonical formatting
lox logic compile                        # base + module + lock → out.Loxone, lock updated
lox config diff base.Loxone out.Loxone   # what changes, by name, page by page
lox logic lint                           # unused names, blocks whose outputs feed nothing

lox config diff is the readable review: names, pages and values. lox logic diff --exit-code is the same comparison by UUID, with exit code 1 when anything differs (for scripts and CI). lox logic diff --summary says it as a commit message, by title and port name: its first line is the subject.

base.Loxone → out.Loxone

= 2 added · 1 parameter · wires +4 −0

Beschattung
  + block  Temp über 28 (GreaterEqual)
  + block  temp_hoch.Q and sonne.Q (And)
  ~ param  Beschattung Süd · TargetPos  100 → 70
  + wire   Außentemperatur.Q → Temp über 28.Input1
  + wire   Sonnenschein.Q → temp_hoch.Q and sonne.Q.I2
  + wire   Temp über 28.Q → temp_hoch.Q and sonne.Q.I1
  + wire   temp_hoch.Q and sonne.Q.Q → Beschattung Süd.AutoShade

That is the example above compiled: the expression became an And block, labeled with the expression so it stays readable in Loxone Config.

Deploy with lox config push

lox config push              # dry run: download live, drift check, compile, show the changes, stage
lox config push --force      # … then upload, restart the program, verify, move base forward
lox config sync              # read-only: source, lock and the Miniserver agree
lox config merge             # take over rules edited in the app first, so the push loses nothing
git add -A && git commit -m "Beschattung: Süd fährt bei 28° auf 70%"

Each step stops the push when it fails:

  1. Download what the Miniserver runs now (backups/<stamp>-pre-push.zip) and list its custom changes. Check that the automatic rules didn’t change since the last push.
  2. Drift check: the live logic must still be your base.
  3. Compile against the live download, so users, passwords, access rights and layout stay as they are live.
  4. Show the changes and compare the live users with the program file.
  5. Stage the upload and check that it extracts to exactly the compiled file. Without --force, the push ends here.
  6. Upload as /prog/sps_new.zip and restart the program, as a save from Loxone Config does.
  7. Download again: the Miniserver must run exactly the compiled file, or the project stays as it was.
  8. Update the lock, out, base in lox.toml and autopilot.changed. Commit them.

Custom changes are what the app, the web UI or the API changed and Loxone Config hasn’t saved yet: light moods, timers, automatic rules, users, NFC tags and codes. The download doesn’t contain them and the upload would delete them, so --force refuses and names them. If your module grants or revokes access (above), the push also updates permissions.bin. Details, including the app catalogue and the JSON report: COMMANDS.md › config push.

Flag When
--allow-removals You deleted managed blocks from the module and want them gone from the config
--accept-version <v> The base was saved by a newer Loxone Config release
--patched-from <dl.Loxone> Your base is a byte patch of that download
--backup-dir <dir> Downloads and artifacts elsewhere (default backups/, git-ignored: configs hold personal data)
--discard-custom-changes Push although the Miniserver holds custom changes, deleting them
--allow-app-changes The rules’ change time moved, and lox autopilot changed --explain shows no rule change
-o json A machine-readable report on stdout

Automatic rules edited in the app: lox config merge rewrites their rule declarations from the live config, moves base to the download and records the change time. Commit, then push. Details: COMMANDS.md › config merge.

To keep custom changes, load the project from the Miniserver in Loxone Config and save it. The live config then differs from your base: bring the project up to date as below, then push.

Roll back by uploading the download from before the push:

lox config upload backups/<stamp>-pre-push.zip --force && lox reboot --yes

When someone else changed the config

Loxone Config, the app and the Miniserver itself also write the config. Check before you edit:

lox config download --extract --save-as live.zip
lox logic drift live.Loxone              # exit 0: in sync with the last compile; 1: someone wrote since
lox config diff base.Loxone live.Loxone   # what they changed

If they changed something you don’t manage, lox config merge takes it over: it points base at the download and compiles again (by hand: point base in lox.toml at live.Loxone and compile). If they touched a managed block, bring the module up to date first (or lox logic adopt --uuid a block they added).

Tests, CI and editors

  • Tests: test "…" … end blocks in a module set inputs, advance time and expect outputs. lox logic test runs them against the compiled config in the Lox Logic simulator, which models the blocks Loxone documents and names any other block a test depends on (simulator.md).
  • CI: examples/ci.sh checks parsing, formatting, lock currency and byte-determinism. --sync also requires the sources to match the deployed config.
  • No personal data in git: a real config carries the address, users, codes and serials. lox logic scan <file|dir> lists where (element and attribute, never the value) and exits 1, so a CI step or pre-commit hook can refuse it.
  • Rename safely: lox logic rename old_slug new_slug renames across all files and the lock, identities kept.
  • VS Code: syntax highlighting and snippets in editor/vscode.
  • AI agents: lox logic check --json gives machine-readable errors. The agent guide has the rules.

Reference

Doc Contents
Lox Logic README Overview, every CLI command, library use
language.md The .loxl language
lockfile-spec.md The lockfile format
vision.md Why, and the “three writers, one file” model