Quick Apps — net.TCPSocket

Class for handling the TCP connection.

TCPSocket class methods

net.TCPSocket(options)

TCPSocket class constructor.

Parameters

options - (optional) argument as a table containing options for the connection:
- timeout - (of type number) expressed in milliseconds.
- tls – (of type table) set if the secure connection is required. This option enables TLS (may be an empty table). Following members can be provided within tls.options:
  - clientCertificate – (of type string) client certificate in PEM format.
  - allowUnauthorized – (of type bool) if you are using a self-signed certificate, pass true. Beware that you are exposing yourself to man in the middle attacks, so it is a configuration that is not recommended for production environments.
  - certificateAuthority – (of type string) a trusted certificate used for server verification. The certificate must use the PEM format.

Example

1function QuickApp:onInit()
2    self.sock = net.TCPSocket({timeout = 10000})
3end

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

1function QuickApp:onInit()
2    self.sock = net.TCPSocket()
3
4    self.sock:connect(self.ip, self.port, {
5        success = function()
6            self:debug("connected")
7        end,
8        error = function(message)
9            self:debug("connection error:", message)
10        end,
11    }
12end

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

1self.sock:read({
2    success = function(data)
3        self:debug(data)
4    end,
5    error = function(message)
6        self:debug(message)
7    end
8})

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

1function QuickApp:waitForResponseFunction()
2    self.sock:readUntil("STOP", {
3        success = function(data)
4            self:debug(data)
5            self:waitForResponseFunction() -- looping the data readout
6        end,
7        error = function()
8            self:debug("response error")
9        end
10    })
11end

TCPSocket:write(data, callbacks)

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

Parameters

data - string 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

1function QuickApp:send(strToSend)
2    self.sock:write(strToSend, {
3        success = function()
4            self:debug("data sent")
5        end,
6        error = function(err)
7            self:debug("error while sending data")
8        end
9    })
10end

TCPSocket:close()

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

QuickApp example

1-- Quick App template for handling the TCP device
2
3function QuickApp:turnOn()
4    self:debug("binary switch turned on")
5    self:send("Some command for on\n") -- sending data to the device. In a normal implementation it will be a code with an appropriate command.
6    self:updateProperty("value", true)
7end
8
9function QuickApp:turnOff()
10    self:debug("binary switch turned off")
11    self:send("Some command for off\n") -- sending data to the device. In a normal implementation it will be a code with an appropriate command.
12    self:updateProperty("value", false)
13end
14
15-- the method for sending data to the device
16-- the method can be called from anywhere
17function QuickApp:send(strToSend)
18    self.sock:write(strToSend, {
19        success = function() -- the function that will be triggered when the data is correctly sent
20            self:debug("data sent")
21        end,
22        error = function(err) -- the function that will be triggered in the event of an error in data transmission
23            self:debug("error while sending data")
24        end
25    })
26end
27
28-- method for reading data from the socket
29-- since the method itself has been looped, it should not be called from other locations than QuickApp:connect
30function QuickApp:waitForResponseFunction()
31    self.sock:read({ -- reading a data package from the socket
32        success = function(data)
33            self:onDataReceived(data) -- handling of received data
34            self:waitForResponseFunction() -- looping of data readout
35        end,
36        error = function() -- a function that will be called in case of an error when trying to receive data, e.g. disconnecting a socket
37            self:debug("response error")
38            self.sock:close() -- socket closed
39            fibaro.setTimeout(5000, function() self:connect() end) -- re-connection attempt (every 5s)
40        end
41    })
42end
43
44-- a method to open a TCP connection.
45-- if the connection is successful, the data readout loop will be called QuickApp:waitForResponseFunction()
46function QuickApp:connect()
47    self.sock:connect(self.ip, self.port, { -- connection to the device with the specified IP and port
48        success = function() -- the function will be triggered if the connection is correct
49            self:debug("connected")
50            self:send("Hello!\n")
51            self:waitForResponseFunction() -- launching a data readout "loop"
52        end,
53        error = function(err) -- a function that will be triggered in case of an incorrect connection, e.g. timeout
54            self.sock:close() -- closing the socket
55            self:debug("connection error")
56            fibaro.setTimeout(5000, function() self:connect() end) -- re-connection attempt (every 5s)
57        end,
58    })
59end
60
61-- function handling the read data
62-- normally this is where the data reported by the device will be handled
63function QuickApp:onDataReceived(data)
64    self:debug("onDataReceived", data)
65end
66
67function QuickApp:onInit()
68    self:debug("onInit")
69
70    self.ip = self:getVariable("ip")
71    self.port = tonumber(self:getVariable("port"))
72
73    self.sock = net.TCPSocket() -- creation of a TCPSocket instance
74    self:connect()
75end