Config as Code (Lox Logic)
Write Miniserver logic as text, review it in a pull request, deploy it verified.
Table of contents
- How it works
- The language in one example
- Set up a project
- The edit loop
- Deploy with
lox config push - When someone else changed the config
- Tests, CI and editors
- 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
externnames an object Loxone Config owns, matched byuuid,inameortitle. You can wire to it, not create it. A title that repeats can be narrowed byroom:,category:ordevice:(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%), andtemplate … endstamps 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:
- 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. - Drift check: the live logic must still be your
base. - Compile against the live download, so users, passwords, access rights and layout stay as they are live.
- Show the changes and compare the live users with the program file.
- Stage the upload and check that it extracts to exactly the compiled file. Without
--force, the push ends here. - Upload as
/prog/sps_new.zipand restart the program, as a save from Loxone Config does. - Download again: the Miniserver must run exactly the compiled file, or the project stays as it was.
- Update the lock,
out,baseinlox.tomlandautopilot.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 "…" … endblocks in a module set inputs, advance time andexpectoutputs.lox logic testruns 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.
--syncalso 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_slugrenames across all files and the lock, identities kept. - VS Code: syntax highlighting and snippets in editor/vscode.
- AI agents:
lox logic check --jsongives 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 |