quickapp-types

QuickApp Device Types and Headers

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

Starter Lua templates are in the templates/ directory — reference them when the user needs a working skeleton for a specific device type.

---

plua Header Syntax

--%%key:value

Headers are Lua comments processed by plua 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 plua library file, use --%%file:$fibaro.lib.libraryName,alias (e.g. --%%file:$fibaro.lib.qwikchild,qwikchild)

Development & Debug Headers

--%%debug:true        -- verbose debug logging
--%%desktop:true      -- auto-open QuickApp UI desktop window
--%%offline:true      -- run without HC3 connection
--%%breakonload:true  -- pause in debugger immediately on load
--%%save:state.json   -- persist state across restarts
--%%project:1001      -- associate with HC3 device ID for upload/sync
--%%proxy:true        -- enable proxy mode (sync with real HC3 QA)
--%%qacolor:lightblue -- background color of the QA desktop window

---

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",onToggled="handleSwitch"}
-- event.values[1] == true/false (boolean)

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

Type	Required Actions	Value / Notes
com.fibaro.binarySwitch	turnOn, turnOff	value = boolean
com.fibaro.multilevelSwitch	turnOn, turnOff, setValue	value = 0–99
com.fibaro.colorController	turnOn, turnOff, setValue, setColor	value = 0–99, color = "r,g,b,w" string e.g. "200,10,100,255"

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

Binary Sensors

All update value (boolean). No required actions.

Type	Typical use
com.fibaro.binarySensor	Generic open/closed
com.fibaro.doorSensor	Door/window
com.fibaro.windowSensor	Window
com.fibaro.motionSensor	PIR motion
com.fibaro.smokeSensor	Smoke detector
com.fibaro.fireDetector	Fire detector
com.fibaro.floodSensor	Water/flood
com.fibaro.waterLeakSensor	Water leak
com.fibaro.gasDetector	Gas leak
com.fibaro.coDetector	Carbon monoxide
com.fibaro.rainDetector	Rain
com.fibaro.heatDetector	Heat detector

Template: binary-sensor.lua

Numeric Sensors

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

Type	Value format
com.fibaro.temperatureSensor	{value=21.5, unit="C"}
com.fibaro.humiditySensor	number 0–100
com.fibaro.lightSensor	number (lux)
com.fibaro.multilevelSensor	number
com.fibaro.energyMeter	number (kWh)
com.fibaro.powerMeter	number (W)
com.fibaro.rainSensor	number (mm/h)
com.fibaro.windSensor	number (m/s)

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:

Type	Extra Actions	Extra Properties
com.fibaro.thermostat	setThermostatMode, setHeatingThermostatSetpoint, setCoolingThermostatSetpoint	heatingThermostatSetpoint, coolingThermostatSetpoint
com.fibaro.thermostatHeat	setThermostatMode, setHeatingThermostatSetpoint	heatingThermostatSetpoint
com.fibaro.thermostatCool	setThermostatMode, setCoolingThermostatSetpoint	coolingThermostatSetpoint
com.fibaro.thermostatHeatCool	setThermostatMode, setHeatingThermostatSetpoint, setCoolingThermostatSetpoint	heatingThermostatSetpoint, coolingThermostatSetpoint

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

Type	Required Actions
com.fibaro.thermostatSetpoint	setHeatingThermostatSetpoint, setCoolingThermostatSetpoint
com.fibaro.thermostatSetpointHeat	setHeatingThermostatSetpoint
com.fibaro.thermostatSetpointCool	setCoolingThermostatSetpoint
com.fibaro.thermostatSetpointHeatCool	setHeatingThermostatSetpoint, setCoolingThermostatSetpoint

HVAC System types — same interface as full thermostat counterparts:

Type	Actions
com.fibaro.hvacSystemHeat	setThermostatMode, setHeatingThermostatSetpoint
com.fibaro.hvacSystemCool	setThermostatMode, setCoolingThermostatSetpoint
com.fibaro.hvacSystemHeatCool	setThermostatMode, setHeatingThermostatSetpoint, setCoolingThermostatSetpoint
com.fibaro.hvacSystemAuto	setThermostatMode, setHeatingThermostatSetpoint, setCoolingThermostatSetpoint

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

Type	Required Actions	Notes
com.fibaro.windowCovering	open, close, stop, setValue	value = 0–99 (% open)
com.fibaro.deviceController	(none — generic)	define your own methods
com.fibaro.remoteController	(none)	call self:emitCentralSceneEvent(keyId, keyAttribute) to emit button events; keyAttribute defaults to "Pressed"
com.fibaro.alarmPartition	arm, disarm	armed = boolean, alarm = boolean

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

Special

Type	Required Actions	Properties
com.fibaro.player	play, pause, stop, next, prev, setVolume, setMute	volume (0–100), mute (boolean), power (boolean)
com.fibaro.weather	(none)	Temperature {value=n,unit="C"}, Humidity (number), Wind (number) — note capital property names
com.fibaro.genericDevice	(none)	No specific interface contract

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