Quick Apps are used to extend the capabilities of the FIBARO System. It enables you to create new integrations in the system that support TCP/IP devices or create specific connected devices.
The entire code written within a given Quick App is running in one environment. It refers to both the main code and the code for controlling the controls. This makes it possible, for example, to create a TCP connection in the main part of the code and use it in the code to operate buttons.

Integration with the system

A device created as a Quick App can be used in the system just like any other device. A device created in this way can be used in scenes, connected devices, etc. To achieve the best level of integration, it is best to choose the appropriate device type, e.g. when integrating a dimmable light bulb, it is best to choose the type of multi-level switch.

Lua

The Lua code written in Quick Apps is slightly different from the code written in scenes. Quick Apps uses an object-oriented programming paradigm that helps to structure the written Lua code.
You can read more about object-oriented programming in Lua here (https://www.lua.org/pil/16.html).

Quick App Class

The QuickApp class is used to represent the created device. It has built-in methods for updating properties, updating device view, downloading variables, etc. To extend the Quick App class we can add methods to it.

This method can be called by self:myMethod()

self

self is an object that can be used inside the Quick App class. It is a reference to ‘itself’. Similar solutions can be found in programming languages such as python or this in javascript. Please note it is only available inside the class methods.

You can add your variables to the self, which can then be used in other methods. This allows us to avoid creating global variables.

onInit

This is the method that is called when the system starts the Quick App. This happens at the system startup and after each saving of the device. It is a place where you can initialize variables, establish a connection with the device, etc.
Defining this method is not required for the Quick App to work properly.

View setup – controls support (firmware 5.030)

There are three types of controls:

  • label
  • button
  • slider

The button and slider can handle events. Button emits onReleased event, and slider emits onChanged event to inform about the change. Events are visible in the control’s edit mode. You can enter name of the method from QuickApp class, that should handle the event. When the event occurs on the control, parameter event of table type will be passed to the method, with the following fields:

  • deviceId – field of int type with the identificator of the device that emitted the event,
  • values – field of table type with values passed by the control. Used only for slider, its value is passed in first position of the table,
  • eventType – field of string type contains event type,
  • elementName – field of string type contains name of the control that emitted the event.

For example slider configured as below:

method with name onSliderChanged should be implemented. Code example below:

For the label control, events cannot be handled. All controls can be updated by the QuickApp:updateView method.

View setup – controls support (firmware 5.021)

There are three types of controls:

  • label
  • button
  • slider

The button and slider can handle events. You can use the self object (as in methods) in the code to handle the controls. This means that all methods and variables assigned to the self object in the main part of the code can also be used here.
When handling a slider change, the new state can be obtained from the value variable.

For the label control, events cannot be handled. All controls can be updated by the QuickApp:updateView method.

Methods within the QuickApp class

The following set of methods is available in QuickApp class. As described earlier, they can be called inside the QuickApp class methods by self:<method name>().

QuickApp:debug(message, …)

A method for displaying messages of type DEBUG in the log window (under the code editor). The variables can be of any type, as they will be converted into text using the tostring function and separated by a single space.

QuickApp:trace(message, …)

A method similar to the QuickApp:debug method. The only difference is that it displays messages of type TRACE instead of DEBUG. Method is available for firmware 5.030 or higher.

QuickApp:warning(message;, …)

A method similar to the QuickApp:debug method. The only difference is that it displays messages of type WARNING instead of DEBUG. Method is available for firmware 5.030 or higher.

QuickApp:error(message, …)

A method similar to the QuickApp:debug method. The only difference is that it displays messages of type ERROR instead of DEBUG. Method is available for firmware 5.030 or higher.

QuickApp:getVariable(variable_name)

The method is used to get the Quick App variables. Variables can be added from the device configuration or the method QuickApp:setVariable.

QuickApp:setVariable(variable_name, value)

The method for setting device variables.

QuickApp:updateProperty(device_property, value)

The method for updating device properties.

QuickApp:updateView(component_name, component_attribute, value)

The method for updating the device view.

Mapping actions to methods

This mechanism allows you to manage the actions of the device. Each action sent to the device (e.g. from the scene), is mapped to the method in the Quick App. The name of the action is mapped to the name of the method. The arguments of the action are passed as arguments of the method.

Looping up the execution

The execution of the QuickApp code is not looped in any way. It is also not necessary for its proper functioning. An example of simple loops is shown below.

net.HTTPClient

Class for handling HTTP/HTTPS queries.

net.HTTPClient(options)

HTTPClient class constructor.

Parameters

  • options – (optional) The argument of table type with options for connection. The only option that can be set is a timeout expressed in milliseconds.

Example

HTTPClient:request(address, params)

A method to execute HTTP/HTTPS queries.

Parameters

  • address – the argument of the string type with the address to which the query is to be executed. e.g. http://127.0.0.1/api/users, https://google.com
  • params – (optional) the argument of the table type. The argument may contain options for the query and/or feedback functions. The possible parameters are described below

items of the params array

  • options – an array of query options. Possible options:
    • checkCertificate – A boolean field that says whether to verify the certificate (default true). This field is only used for HTTPS connection
    • method – a field of the type string which contains the name of the http method (e.g. GET)
    • data – a field of type string that contains the query body
    • headers – a field of type table, which contains query headers
  • success(response) – The function will be triggered if the data is sent correctly. The data argument passed on is of the table type with the following structure:
    • data – a field of type string containing the response body
    • status – a field of type number containing a response code e.g. 200, 404 etc.
    • headers – a field of type table containing response headers
  • error(message) – The function will be triggered in case of an error when sending data, e.g. disconnection. The parameter message (type string) returns the error content.

Examples

net.TCPSocket

Class for handling the TCP connection.

net.TCPSocket(options)

TCPSocket class constructor.

Parameters

  • options – (optional) argument as a table containing options for the connection. The only option that can be set is a timeout expressed in milliseconds.

Example

TCPSocket:connect(ip, port, callbacks)

The method establishes the TCP connection to the specified IP and port.

Parameters

  • ip – an argument of the string type with the IP address to establish the connection
  • port – an argument of the number type argument with the port to establish the connection
  • callbacks – (optional) an argument of the type table with callback actions, which will be executed in case of the relevant events described below

Feedback functions:

  • success() – the function will be triggered if the connection is correct
  • error(message) – The function will be triggered in case of an error when trying to connect, e.g. no connection. The parameter message (type string) passes the error message

Example

TCPSocket:read(callbacks)

A method for reading data from a set socket. For proper operation the connection must be set up correctly.

Parameters

  • callbacks – (optional) an argument of the type table with feedback functions, which will be executed if the relevant events described below occur

Feedback functions:

  • succes(data) – the function will be triggered if the data package is read correctly. The data is passed by the data argument, which is of string type
  • error(message) – the function will be triggered in case of an error when trying to read data, e.g. disconnection. The parameter message carries the error content

Example

TCPSocket:readUntil(delimiter, callbacks)

The method reads the data until the given string (delimiter) appears. The method is useful for handling protocols where there is a fixed character or character string that indicates the end of a data packet. The returned data not will contain the character string given as a delimiter.
For proper operation, the connection must be set up correctly.

Parameters

  • delimiter – the argument of the type string which is a limit to which data will be read
  • callbacks – (optional) an argument of the type table with feedback functions, which will be executed if the relevant events described below occur

Feedback functions:

  • success(data) – the function will be called if the data package is read correctly. The data is passed by the data argument, which is of string type
  • error(message) – the function will be called in case of an error when trying to read data, e.g. disconnection. The parameter message carries the error content

Example

TCPSocket:send(data, callbacks)

The method for sending data. The connection must be correctly established for proper operation.

Parameters

  • datastring argument with data to be sent
  • callbacks – (optional) an argument of the type table with feedback functions, which will be executed if the relevant events described below occur

Feedback functions:

  • success() – the function will be triggered if the connection is correct
  • error(message) – the function will be triggered in case of an error when trying to read data, e.g. disconnection. The parameter message carries the error content

Example

TCPSocket:close()

The method used to close the socket and to disconnect the connection.

TCP example

net.UDPSocket

Class for handling the UDP connection.

UDPSocket class methods

net.UDPSocket(options)

UDPSocket class constructor.

Parameters
  • options – (optional) argument as a table containing options for the connection. Avaiable parameters:
    • broadcast – (optional) an argument of the type boolean that turns on the broadcast option
    • timeout – (optional) an argument of the type number with response timeout in milliseconds
Example

UDPSocket:sendTo(data, ip, port, callbacks)

Method sends datagram to provided ip and port.

Parameters
  • data – an argument of the string type with data to be sent
  • ip – an argument of the string type with the IP address to establish the connection
  • port – an argument of the number type argument with the port to establish the connection
  • callbacks – (optional) an argument of the type table with callback actions, which will be executed in case of the relevant events described below
Feedback functions:
  • success() – the function will be triggered if the connection is correct
  • error(message) – The function will be triggered in case of an error when trying to connect, e.g. no connection. The parameter message (type string) passes the error message
Example

UDPSocket:receive(callbacks)

A method for reading data from a socket.

Parameters
  • callbacks – (optional) an argument of the type table with callback actions, which will be executed in case of the relevant events described below
Feedback functions:
  • success(data) – the function will be triggered if the data package is read correctly. The data is passed by the data argument, which is of string type
  • error(message) – The function will be triggered in case of an error when trying to read the data, e.g. timeout. The parameter message (type string) passes the error message

UDPSocket:close()

The method used to close the socket.

MQTT client

Quick Apps in Home Center 3 support communication in MQTT standard by creating MQTT clients. To learn more about MQTT clients click here.

Managing child devices

Quick Apps in Home Center 3 support device inheritance to create multiple interconnected devices. To learn more about managing child devices click here.

Sample Quick Apps to download

To upload the sample to your Home Center 3 go to > Devices > > Other Device > Upload file and choose the downloaded file.

TCP connection sample (for devices like Global Caché)

Download

In this example the Quick App will communicate with another device using TCP protocol. IP address and port can be modified using variables. It consists of 3 buttons: ON button will send “ON” message, OFF button will send “OFF” message and wait for response, sampleHex button will send sample hexadecimal message.

Current weather data from OpenWeatherMap

Download

In this example the Quick App will import weather data for provided location from OpenWeatherMap and display condition, temperature, wind and humidity. Created device can be used as the main weather provided (set in General settings) to use in scenes and interfaces. For the Quick App to work properly you must configure following variables:

  • locationId – ID of one of the locations set in the FIBARO System (General > Location)
  • APIKey – API key for OpenWeatherMap, you can aquire it here: https://openweathermap.org/appid
  • Unit – unit system for the data: metric or imperial

Random temperature

Download

In this example the Quick App will simulate temperature sensor, that changes temperature to random values in random intervals. Using variables you can set: maximum and minimum temperature, maximum and minimum time interval and precision (number of decimals).

Backuper

Download

In this example the Quick App will create backup of the system after clicking the button. The user can change type of the backup (remote or local) using backupType variable.