QuickApp Device Types and Headers

Reference for all flua QuickApp file headers and the complete set of Fibaro device types.

Starter Lua templates are in the templates/ directory — the complete set (30 device types), one file per type, each with the type's canonical actions and property conventions (e.g. multilevelSwitch.lua handles turnOn/turnOff/setValue with value 0-99; temperatureSensor.lua asserts {value=, unit=}). Reference them when the user needs a working skeleton for a specific device type, and scaffold one with flua --tool newQA <type> [name] (lists all types with no argument).

flua Header Syntax

--%%key:value

Headers are Lua comments processed by flua before execution. All headers must appear before any Lua code.

Device Configuration Headers

--%%name:My QuickApp            -- display name (required)
--%%type:com.fibaro.binarySwitch -- device type (required)
--%%manufacturer:ACME Corp
--%%model:SmartDevice v1.0
--%%description:What this device does
--%%uid:unique-id-string

Variable Headers

--%%var:apiKey="abc123"          -- string value: must be a Lua string literal
--%%var:location="Stockholm"     -- strings need quotes
--%%var:updateInterval=30        -- numbers are Lua literals, no quotes needed

Gotcha: The value is evaluated as a Lua expression. --%%var:X=London evaluates the global London (likely nil). Use --%%var:X="London" for strings.

Interface Headers

--%%interfaces:{"battery","energy"}

Multi-file Headers

--%%file:./lib/utils.lua,utils   -- include external Lua file (path, module name)

To include a library file, use --%%file:$fibaro.lib.libraryName,alias (e.g. --%%file:$fibaro.lib.qwikchild,qwikchild)

Development & Debug Headers

--%%debug:refreshState=true,api=true,http=true  -- debug logging channels
--%%offline:true      -- legacy alias for --%%mode:offline
--%%mode:online|offline|proxy  -- runtime mode; proxy needs online + HC3 credentials
--%%warn:true         -- extra runtime warnings (e.g. api error statuses)
--%%db:file.json      -- seed data; --%%db:+file.json also persists state across restarts
--%%location:latitude=N,longitude=N  -- pin the sim's location (sun times)
--%%keep-alive:true   -- online: keep the run alive past idle
--%%scene:true        -- run this QA as an HC3 Lua scene
--%%uid:x / --%%description:x / --%%model:x / --%%build:x / --%%manufacturer:x
                      -- device properties
--%%clobber:name=value -- plua's --%%conceal: the PACKAGE value, taken RAW
                      -- (no Lua evaluation — don't quote it)

--%%save, --%%desktop, --%%breakonload, --%%project and --%%qacolor are plua directives flua does not implement (ignored/unknown) — remove them when migrating. --%%proxy:true is the legacy alias for --%%mode:proxy, not a casual flag.

UI Element Headers

Each --%%u: line defines one row. Use {{...},{...}} for multiple elements on the same row.

Label

--%%u:{label="statusLbl",text="Status: Ready"}

Button

--%%u:{button="myBtn",text="Click Me",onReleased="handleClick"}
-- callback: function QuickApp:handleClick(event) end

Switch (toggle)

--%%u:{switch="autoSwitch",text="Auto Mode",value="false",onToggleOn="handleOn",onToggleOff="handleOff"}
-- 5.221 split events (also onReleased); event.values[1] == "true"/"false" (string)

Slider

--%%u:{slider="brightSlider",text="Brightness",min="0",max="100",value="50",onChanged="handleSlider"}
-- use tonumber(event.values[1]) to get numeric value

Select (single-choice)

--%%u:{select="modeSelect",text="Mode",value="1",onToggled="handleSelect",
--      options={{type='option',text='Economy',value='1'},{type='option',text='Comfort',value='2'}}}

Multi (multi-select)

--%%u:{multi="tagMulti",text="Tags",values={"1","3"},onToggled="handleMulti",
--      options={{type='option',text='Tag A',value='1'},{type='option',text='Tag B',value='2'}}}

Multiple elements on one row

--%%u:{{button="onBtn",text="On",onReleased="turnOn"},{button="offBtn",text="Off",onReleased="turnOff"}}

Updating dropdowns at runtime

Single-select (select) — use "selectedItem" to set the current selection:

self:updateView("modeSelect", "options", {{type='option',text='Economy',value='1'},{type='option',text='Comfort',value='2'}})
self:updateView("modeSelect", "selectedItem", "1")   -- value string of the selected option

Multi-select (multi) — use "selectedItems" to set selected values, "options" to update the list:

self:updateView("tagMulti", "options", {{type='option',text='Tag A',value='1'},{type='option',text='Tag B',value='2'}})
self:updateView("tagMulti", "selectedItems", {"1","3"})  -- table of selected value strings

Gotcha: Using "values" instead of "selectedItems" (or "selectedItem" for single-select) will silently fail or have no effect on the HC3.

UI event callback pattern

function QuickApp:handleClick(event)
    -- event.deviceId, event.elementName, event.eventType, event.values
    self:debug("clicked:", event.elementName)
end

function QuickApp:handleSlider(event)
    local value = tonumber(event.values[1])
    self:updateView("brightSlider", "value", tostring(value))
end

Device Type Quick Reference

Switches

Templates: binary-switch.lua · multilevel-switch.lua · color-controller.lua

Binary Sensors

All update value (boolean). No required actions.

Template: binary-sensor.lua

Numeric Sensors

All update value as number or {value=n, unit="C"}. No required actions.

Template: templates/numeric-sensor.lua

Climate / Thermostat

All thermostat setpoint/temperature values use {value=n, unit="C"} format.

Full thermostat types — handle setThermostatMode, update thermostatMode, supportedThermostatModes, temperature:

Setpoint-only types — no mode, just setpoints + temperature:

HVAC System types — same interface as full thermostat counterparts:

Templates: thermostat.lua (full) · thermostat-heat.lua · thermostat-cool.lua · thermostat-heatcool.lua · thermostat-setpoint-heat.lua · thermostat-setpoint-cool.lua · thermostat-setpoint-heatcool.lua

Covers and Controllers

Templates: controller.lua · window-covering.lua · alarm-partition.lua · remote-controller.lua

Special

Templates: player.lua · weather.lua · generic-device.lua