flua documentation

Shipped with flua — this page and everything below it come from the installed package, so the docs always match your version.

Guides

The tutorial series

  1. Develop QuickApps on your laptop — meet flua — install, first QA, `--ui` viewer, `--tool setup`, F5
  2. Design your QuickApp UI without the controller — `--%%u` (label/button/slider/switch/select/multi), viewer interactions, updateView, `json.array()`
  3. Time travel for your timers and scenes — virtual clock: `--%%time:`/`--%%speed`/`--%%instant`/`--%%maxhours` directives + `--start`/`--speed`/`--instant` flags, setTimeout scheduling
  4. Debug HC3 Lua in VS Code — breakpoints included — mobdebug launch configs, clock pauses while debugging, `--debugger`, `--check`
  5. Run a whole house: many QAs, one flua — multi-QA runs, find-device-by-name, qa3/qa4, trigger.lua, `--seed`
  6. Let your QA test itself — self-asserting QAs (selfTest.lua), exit codes, quickapp-test skill for agents, `require()` test libs
  7. From laptop to HC3 with one command — `.env`, downloadQA/updateQA/uploadQA/pack/uploadFQA, uploadFile single-file updates + VS Code task, online mode, proxy mode mention
  8. Mock your integrations: HTTP, TCP, UDP and WebSocket servers in Lua — `net.*Server`, mockServer.lua, stateful handlers, require'd mocks
  9. The device catalog: 30 device types, one command — `--tool newQA`, type templates + canonical actions, quickAppVariables
  10. Multi-file QAs: grow your project, keep it organized — `--%%file` + EOH, load order, files API, `require` vs packaged files
  11. Listen to the house: the refreshState event flow — RefreshStateSubscriber, event shape, predicates, `/refreshStates`
  12. Child devices, the HC3 way — QuickAppChild + createChildDevice (basic HC3 API — not QwikAppChild), parentId, removeChildDevice
  13. Develop a QA together with your agent — agent verify loop (exit codes, PASS/FAIL), --tool setup skills + LuaLS types, virtual clock in the loop (--instant, --start), driving the sim over HTTP, net.*Server mocks, require'd test libs
  14. Keep your secrets out of your QuickApp — configs, env and --%%var — `.flua.lua` config file, `.env` chain + `os.getenv`, `--%%var` expressions (tables, nil-unset, faulty-expr errors), package values (`--%%var`,...,""/`--%%clobber`) vs uploadQA, quickAppVariables round-trip
  15. Real integrations: HTTP and MQTT from your QuickApp — `net.HTTPClient` (GET/POST, success/error callbacks, timeout), `mqtt.Client` (events, QoS, echo demo, MQTT_URL override, TLS + `useSNI`), mock→real loop
  16. Meet flua-mcp: flua as a tool your agent can call — `flua-mcp` (stdio + Streamable HTTP transports, dual-era protocol), tools (`qa_check`/`qa_run` with summary+filter, `qa_ui`, sessions `qa_start`/`qa_probe`/`qa_action`/`qa_stop`), resources (`flua://docs/*`), prompts (`qa_debug`/`qa_skeleton`), host registration (Claude Desktop, Copilot, remote URL)
  17. Mock a Modbus device — develop your Modbus client on the laptop — `examples/Modbus Server/` (SolarEdge SunSpec mock + generic modbus_server.lua, buttons, dual wire-base serving), minimal SunSpec client QA, launch config with two QAs, `-D var:host` override, downloadQA+unpack for existing QAs
  18. Test foreign QAs without touching them — `.flua-directives` next to the main file (tester wins over the QA's header), `-D` on top, `os.getenv` expressions, the full precedence chain
  19. The flua VS Code extension — marketplace install (`GsonSoft-development.flua`), explorer tool menus, the `.fqa` viewer (metadata + Lua previews), check-on-save; pack/unpack naming (`.fqa`, `_main.lua`), identity properties traveling in packages
  20. A test suite for your QuickApps — `require("flua-test")` assertions, `flua test` discovery + per-file timeout, PASS/FAIL/TIME report, exit codes for CI
  21. flua doctor — one command says why it doesn't work — nine checks: runtime, venv, HC3 credentials/reachability (secrets never echoed), LuaLS/.vscode setup, extension, flua-mcp; `--no-network`, `--json`
  22. Record & replay the real house — `flua record` (device snapshot + refreshStates feed), `--replay`/`--%%replay` on the virtual timeline, RefreshStateSubscriber reactions, `--speed`/`--instant`, recording doubles as `--seed`
  23. How much of the HC3 does flua cover? — `flua audit` (routes, device catalog, QA templates — pinned floors), the type hierarchy fallback for unknown device types (`devices/hierarchy.json`)
  24. Traces your agent can read — `--%%trace`/`--%%syslog` as directives (header/include/.flua-directives), the one-JSON-line-per-event stream, categories, truncation, `/flua/systemLog` + MCP system events
  25. The run timeline: your QA's story, drawn — `/timeline` under `--ui`: one lane per QA (+ a separate timer lane), virtual time on the x-axis, colored marks with stacked-event tooltips, fixed time scale with horizontal scroll, clear-without-recompressing, `--speed`/`--instant` interplay
  26. Your feedback loop — now with an issue for it — the feedback issue template + labels, the copy-paste prompt so your coding agent files the report, what happens after (verify → fix with pinning tests → rainy-day parking → response)
  27. Stop clicking — automate your UI tests — the self-asserting UI-interaction pattern (`examples/ui-interaction-test.lua`), the data-driven whole-UI suite (`examples/ui-interaction-suite.lua`), wait-for-async-callback polling, `--strict-tests` + `--result-json` for CI
  28. Your house, simulated: 30 device types, one call each — `_FLUA.loadSimDevice` (bundled sim devices, pip install included), the uniform fibaro.call drivers (setValue/setUnit/breach/clearBreach/turnOn/…), viewer status panels, `_FLUA.keepAlive()`, the weather simulator QA
  29. Give the simulated HC3 its own REST surface — `api.registerEndpoint` (additive + `override=true`), the mock-panels module/consumer pair, handler-on-the-pump semantics (setTimeout, postRefreshEvent), the alarm-logic override loop, the weather simulator as an endpoint QA

Standalone posts