quickapp-api

name

quickapp-api

description

Full HC3 QuickApp Lua API reference: fibaro.* functions, QuickApp methods (self:updateProperty, self:updateView, self:getVariable, etc.), plugin.* API, api.* REST calls, net.HTTPClient/TCPSocket, timers (setTimeout/setInterval), JSON, and standard Lua libraries available in QA context. USE FOR: writing QuickApp code, looking up specific method signatures, understanding what functions are available, fixing "attempt to call nil" errors on QA methods.

QuickApp Lua API Reference

Complete reference for the Fibaro HC3 QuickApp Lua programming environment. Use this skill when writing QuickApp code with plua.

---

QuickApp Lifecycle

Every QuickApp starts with onInit(). The global quickApp variable is set only after onInit() returns.

function QuickApp:onInit()
    self:debug("Started, id =", self.id, "name =", self.name)
    -- initialize timers, load variables, etc.
end

---

QuickApp Methods (self:...)

Logging

self:debug(...)    -- DEBUG level — shown in HC3 debug console
self:trace(...)    -- TRACE level
self:warning(...)  -- WARNING level
self:error(...)    -- ERROR level

All logging methods accept multiple arguments separated by commas; they are concatenated with spaces.

Device Properties

self:updateProperty("value", true)       -- persist and trigger events
self:updateProperty("log", "status msg") -- update log field
-- self.properties.value = true  ← DO NOT do this, no event generated

Common property names: value, dead, log, userDescription.

QuickApp Variables

local v = self:getVariable("myKey")   -- returns "" if not found (not nil!)
self:setVariable("myKey", "myValue")  -- triggers DevicePropertyUpdatedEvent
-- Always check: if v ~= "" then ...

UI Updates

self:updateView("labelId", "text", "Hello world")
self:updateView("sliderId", "value", "75")      -- value must be a STRING
self:updateView("btnId", "text", "Click me")
self:updateView("switchId", "value", "true")    -- "true" or "false" as string

Children

-- Create a child device
local child = self:createChildDevice({
    name = "My Child",
    type = "com.fibaro.binarySwitch",
    initialProperties = { value = false }
}, ChildClass)  -- ChildClass is your class extending QuickAppChild

-- Load existing children at startup (call in onInit)
self:initChildDevices({ ["com.fibaro.binarySwitch"] = ChildClass })

-- Remove a child
self:removeChildDevice(childId)

Actions and Interfaces

self:callAction("myMethod", arg1, arg2)   -- dispatch to self method
self:addInterfaces({"energy", "battery"}) -- add device interfaces
self:hasInterface("energy")               -- returns boolean

Properties on self

Property	Type	Description
self.id	number	Device ID
self.name	string	Device name
self.type	string	Device type string
self.properties	table	Full properties (read-only reference)

---

fibaro.* Global API

Device Control

fibaro.call(deviceId, "turnOn")               -- invoke action on device
fibaro.call(deviceId, "setValue", 75)         -- with argument
fibaro.getValue(deviceId, "value")            -- returns value only
fibaro.get(deviceId, "value")                 -- returns (value, modifiedTimestamp)
fibaro.getDevicesID(filter)                   -- returns array of IDs matching filter

Since fw ≥ 5.031.33, fibaro.call is async by default. For self-calls use self:method(). Control with fibaro.useAsyncHandler(true/false).

Device Metadata

fibaro.getName(deviceId)
fibaro.getType(deviceId)
fibaro.getRoomID(deviceId)
fibaro.getRoomName(roomId)
fibaro.getRoomNameByDeviceID(deviceId)
fibaro.getSectionID(deviceId)

Global Variables

fibaro.getGlobalVariable("myVar")         -- returns string value
fibaro.setGlobalVariable("myVar", "val")  -- set value

Scenes & Profiles

fibaro.scene("execute", sceneId)
fibaro.scene("kill", sceneId)
fibaro.profile(profileId, "activateProfile")

Alarms & Notifications

fibaro.alarm(partitionId, "arm")          -- arm/disarm partition
fibaro.alert("email", {userId}, "msg")    -- send notification
fibaro.alert("push", {userId}, "msg")
fibaro.emitCustomEvent("myEventName")     -- fire custom event

Logging (global)

fibaro.debug(tag, message)
fibaro.trace(tag, message)
fibaro.warning(tag, message)
fibaro.error(tag, message)

---

plugin.* API

Lower-level API — prefer self: QuickApp methods where available.

plugin.mainDeviceId               -- current device ID
plugin.createChildDevice(props)   -- create child device
plugin.deleteDevice(deviceId)
plugin.getChildDevices(deviceId)
plugin.getDevice(deviceId)
plugin.getProperty(deviceId, prop)
plugin.restart(deviceId)

---

api.* — Direct REST Calls to HC3

local device = api.get("/devices/25")
local devices = api.get("/devices?interface=zwave")
local result = api.post("/customEvents/myEvent", {})
api.put("/devices/25", { name = "New Name" })
api.delete("/globalVariables/oldVar")

api.* returns the parsed JSON response (Lua table), or nil on error.

Write safety: api.put / api.post against HC3 have several non-obvious silent-failure modes (partial array writes wipe siblings, action POSTs return HTTP 202 even on failure, enum values get silently coerced, etc.). Before writing non-trivial data via api.*, see the hc3-write-safety skill for the read-modify-write + verify pattern.

---

Timers and Scheduling

-- One-shot timer
local ref = setTimeout(function()
    self:debug("fired!")
end, 5000)  -- ms

clearTimeout(ref)

-- Repeating timer
local ref2 = setInterval(function()
    self:debug("tick")
end, 10000)

clearInterval(ref2)

-- setTimeout with 0 yields to pending tasks immediately
setTimeout(function() self:doSomething() end, 0)

Avoid fibaro.sleep(ms) — it blocks all event handling, HTTP callbacks, and timers while sleeping. Always use setTimeout/setInterval patterns instead.

---

net.* — Networking in QuickApps

HTTP Client

local http = net.HTTPClient()
http:request("https://api.example.com/data", {
    options = {
        method = "GET",
        headers = { ["Authorization"] = "Bearer " .. token }
    },
    success = function(response)
        local data = json.decode(response.data)
        self:debug("status:", response.status)
    end,
    error = function(err)
        self:error("HTTP error:", err)
    end
})

TCP Socket

local tcp = net.TCPSocket()
tcp:connect("192.168.1.100", 8080, {
    success = function()
        tcp:write("HELLO\n", {
            success = function() self:debug("sent") end
        })
    end,
    error = function(err) self:error("connect error:", err) end
})
tcp:read({ success = function(data) self:debug("received:", data) end })
tcp:close()

UDP Socket

local udp = net.UDPSocket()
udp:sendTo("data", "192.168.1.100", 9999)

---

JSON

local t = json.decode('{"key": "value", "num": 42}')
local s = json.encode({ key = "value", num = 42 })

Availability: plua vs HC3

Function	plua	HC3
json.encode(t)	✓	✓
json.decode(s)	✓	✓
json.encodeFormated(t)	✓	✗ — plua only
json.util.InitArray(t)	✓	✓

json.encodeFormated produces pretty-printed JSON but is only available in plua. Do not use it in code intended to run on a real HC3 — it will throw a nil-call error. If you need formatted output on the HC3, provide your own implementation.

Marking tables as arrays: json.util.InitArray

By default, an empty or mixed Lua table may encode as {} (object) rather than [] (array). Use json.util.InitArray to force array encoding — this is available on both plua and real HC3 and is essential when posting to REST APIs that require a JSON array:

local arr = json.util.InitArray({})          -- encodes as [] not {}
local items = json.util.InitArray({"a","b"}) -- encodes as ["a","b"]
api.post("/foo", { ids = json.util.InitArray({}) })

Fields that MUST be array-encoded when uploading an FQA

When building an FQA structure to POST to /api/quickApp/, several nested fields are array-typed on HC3. If any of them is empty (or sparse), the JSON encoder will emit {} and HC3 will reject the upload or silently treat the field as missing. Mark them as arrays before encoding:

local function markArray(t) if type(t)=='table' then json.util.InitArray(t) end end

markArray(fqa.initialInterfaces)
markArray(fqa.initialProperties.quickAppVariables)
markArray(fqa.initialProperties.uiView)
markArray(fqa.initialProperties.uiCallbacks)
markArray(fqa.initialProperties.supportedDeviceRoles)

api.post("/quickApp/", json.encode(fqa))

The same care applies whenever you PUT an array-valued property back to /api/devices/{id} (e.g. properties.quickAppVariables, properties.uiCallbacks) — see the hc3-write-safety skill for the full list of array-valued properties and the read-modify-write pattern needed to avoid wiping siblings.

---

Standard Lua Available in QAs

os.time(), os.date(), os.clock(), os.difftime()

string.format(), string.find(), string.gmatch(), string.gsub(), string.sub(), string.split() (Fibaro extension), string.starts() (Fibaro extension)

table.insert(), table.remove(), table.sort(), table.concat()

math.floor(), math.ceil(), math.abs(), math.max(), math.min(), math.random(), math.huge

pcall(f, ...) — protected call; returns (true, result) or (false, errmsg) tostring(), tonumber(), type(), pairs(), ipairs()

---

Key Caveats

• self:getVariable(name) returns "" when missing, not nil
• self:updateView(...) values must be strings — use tostring(n)
• self.properties.* writes are transient — use self:updateProperty() to persist
• All QuickApp methods are publicly callable via fibaro.call(id, "method") — keep private helpers as local functions outside the class
• self.parent is not available during Child:__init() — use child's onInit() instead
• quickApp global is only set after onInit() returns

---

See also

• hc3-write-safety — silent-failure hazards on api.put / api.post writes (partial array wipes, enum coercion, Z-wave cache-only writes, HTTP-202 action failures) and the defensive read-modify-write pattern.
• hc3-rest-api — full HC3 REST endpoint reference.
• quickapp-patterns — common QA implementation patterns (timer loops, refreshStates, child devices).
• quickapp-troubleshooting — known QA quirks and HC3 firmware behaviour differences.