Config Management
The platform keeps a current copy and a full change history of each device’s config and Lua scripts, and detects drift automatically - no polling, no scheduled jobs. The on-device config.json format itself is documented under Firmware Config; this page covers how the platform tracks and versions those files.
Drift detection
Detection is hash-based and reactive:
- Every device publishes a retained
<prefix>/infomessage on connect, and re-publishes it after any state-changing command (for exampleconfig.reload). The payload carries SHA-256 hashes of the on-disk file bytes:config_hash-/config.jsonscripts_main_hash-/scripts/main.luascripts_rules_hash-/scripts/rules.lua
- On each
/info, the app compares every hash against the latest stored hash for that file. - If a hash matches, nothing happens - the stored copy is already current.
- If a hash differs (or the platform has no copy of that file yet), the app pulls the file over MQTT, validates it, and stores it.
Because the firmware re-publishes /info right after a config.reload, a change made on the device surfaces in the platform within about a second.
Pulling a changed file
- config.json is pulled with a single
config.dumpcommand. - Lua scripts are pulled with chunked
fs.cat(paged reads), since a script can exceed the MQTT buffer. See Chunked File I/O.
Pulled content is validated before it is stored: a config must parse as a JSON object, and a script must be non-empty and free of shell-error markers. Invalid pulls are discarded rather than recorded.
What is stored
| Store | Holds |
|---|---|
| current state | one row per (device, path): the file content, its SHA-256, and where the change came from |
| history | an immutable, append-only log; every SHA change is appended with a link to the previous SHA |
A new history row is written only when the content actually changes - a re-reported identical hash does not create one. The result is a forensic chain of every config and script version a device has run, with no duplicate rows.
Where to see it
The per-device config page in the admin interface shows the current config and scripts, their version history, and lets an operator push a change back to the device. See Admin UI.