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

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 in the debug window (under Lua 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: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

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.