← Go back to browsing Knowledge Base articles

[HC3, HC3L, YH] Quick Apps – MQTT client

FIBARO Home Center 3 can act as an MQTT client.

WARNING: this function is available only on Home Center 3, Home Center 3 Lite and Yubii Home with firmware 5.030 or higher.

MQTT features and concept

This document focuses on the implementation of MQTT in Home Center 3, Home Center 3 Lite and Yubii Home.
To find out more about MQTT, its features and concept, please check out the links section.

Callback vs. Event

The parameter options gives the ability to pass a callback. This callback indicates the operation completion but does NOT indicate the message has been received by the broker. The callback must be of the following pattern:

function callback(int errorCode);

1	function callback(int errorCode);

Events signal the availability of packet received from the broker. E.g. onmessage event is signaled when the client receives PUBLISH packet from the broker. All events handlers must be of usual signature:

function callback(table args)

1	function callback(table args)

args parameter is a table and its values depend on the type of event.

Use EventTarget API to register for an event, for example, registering for onmessage event:

function myCallback(event)
  print('Received message: ' .. event.payload);
end
-- NOTE: 'on' prefix omitted
client.addEventListener('message', myCallback);

function myCallback(event)

print('Received message: ' .. event.payload);

end

-- NOTE: 'on' prefix omitted

client.addEventListener('message', myCallback);

Quality of Service

Possible QoS values.

QoS = {
    AT_MOST_ONCE = 0,
    AT_LEAST_ONCE = 1,
    EXACTLY_ONCE = 2,
}
-- can be used: `QoS.AT_LEAST_ONCE`

QoS = {

AT_MOST_ONCE = 0,

AT_LEAST_ONCE = 1,

EXACTLY_ONCE = 2,

}

-- can be used: `QoS.AT_LEAST_ONCE`

mqtt.Client.connect(uri, options)

Asynchronously creates a connection with the broker. When connection is made, onconnected event is triggered.

Parameters

uri – (of type string) the address of the broker. Either full URI with mqtt/mqtts scheme or just a host part. URI Scheme Specification
options – (optional) (of type table) attributes (all are optional):
- - port – (of type number) the port to use for TCP connection. Defaults to 1883 (8883 for TLS).
  - tls – (of type table) TLS options (explained below).
keepAlivePeriod – (of type number) maximum time interval that is permitted between the point at which the Client finishes transmitting one Control Packet and the point it starts sending the next. It allows both sides to determine if the other one is still alive and reachable.
Defaults to zero – keep-alive mechanism is deactivated.
- username and password – (of type string) containing user credentials for client authentication.
- clientId – (of type string) an identifier of each MQTT client connecting to an MQTT broker. If no ID is given, a random ID will be generated.
- cleanSession – (of type bool) indication of the broker, whether the client wants to establish a persistent session or not. Defaults to false.
- callback – function that will be called when the connection attempt is complete.
- lastWill – (of type table) used for notifying other clients, when a client disconnects ungracefully. lastWill members:
- topic – a field of type table containing topic name,
- payload – a field of type string with the content of the last will,
- qos – (optional) QoS of the last will,
- retain – (optional) a field of type bool.

Returns a new client object of MqttClient class.

In case mqtts (mqtt over tls) is required, the options.tls must be provided (may be an empty table). If mqtts scheme is used in URL, TLS usage is also enabled. 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.

connected event – triggered when CONNACK is received from the server. Event arguments:

sessionPresent – boolean that indicates, whether the broker already has a persistent session of the client from previous interactions.
returnCode – number that signals the client, if the connection attempt was successful and otherwise what the issue is. See also ConnectReturnCode enum.

Example

function QuickApp:connect()
  self.client = mqtt.Client.connect(self:getVariable("brokerURI"))
    self.client:addEventListener('connected', function(event) self:onConnected(event) end)
end

function QuickApp:connect()

self.client = mqtt.Client.connect(self:getVariable("brokerURI"))

self.client:addEventListener('connected', function(event) self:onConnected(event) end)

end

mqtt.Client.disconnect(options)

Disconnects client from the broker.

options – (optional) is a table with the following members (all are optional):
- callback – function called when the disconnect attempt is complete.

Parameters

onclosed event – triggered when the connection is closed or broken by other means. Arguments are empty for this event.

mqtt.Client.subscribe(topic, options)

Registers the client in the broker to listen for messages on the given topic. Messages can be filtered with pattern matching as specified in MQTT documentation, i.e. use '#' and '+' characters. Once the client is subscribed, the messages are received through onmessage event.

Parameters

topic – (of type string) a topic to subscribe to.
options – (optional) is a table with following members (all are optional):
- qos – (of type number) the desired quality of service level for the subscription. Defaults to 0. See also QoS enum.
- callback – function called when the disconnect attempt is complete.

Returns packet ID – a unique identifier used to identify the message.

subscribed event – triggered when SUBACK is received from the server. Event arguments:

- packetId – packet ID as returned by subscribe().
- results – (of type table) The broker sends one return code for each topic/QoS-pair it received in the SUBSCRIBE message. If the SUBSCRIBE message had 5 subscriptions, there will be 5 return codes to acknowledge each topic with the QoS level granted by the broker. If the subscription was prohibited by the broker (e.g. if the client was not allowed to subscribe to this topic due to insufficient permission or if the topic was malformed), the broker will respond with a failure return code for that specific topic.
  
  Return Code Return Code Response
  
  0 Success – Maximum QoS 0
  
  1 Success – Maximum QoS 1
  
  2 Success – Maximum QoS 2
  
  -1 Failure

Return Code	Return Code Response
0	Success – Maximum QoS 0
1	Success – Maximum QoS 1
2	Success – Maximum QoS 2
-1	Failure

Example

function QuickApp:subscribe()
    self.client:addEventListener('message', function(event) self:onMessage(event) end)
    self.client:addEventListener('subscribed', function(event) self:onSubscribed(event) end)    

  self.client:subscribe("lights/#", { qos = mqtt.QoS.EXACTLY_ONCE });
end

function QuickApp:onSubscribed(event)
    print("onSubscribed:", json.encode(event))
end

function QuickApp:onMessage(event)
    print("onMessage:", json.encode(event))  

    if event.payload == "ON" then
        self:updateProperty("value", true)
    elseif event.payload == "OFF" then
        self:updateProperty("value", false)
    end
end

function QuickApp:subscribe()

self.client:addEventListener('message', function(event) self:onMessage(event) end)

self.client:addEventListener('subscribed', function(event) self:onSubscribed(event) end)

self.client:subscribe("lights/#", { qos = mqtt.QoS.EXACTLY_ONCE });

end

function QuickApp:onSubscribed(event)

print("onSubscribed:", json.encode(event))

end

function QuickApp:onMessage(event)

print("onMessage:", json.encode(event))

if event.payload == "ON" then

self:updateProperty("value", true)

elseif event.payload == "OFF" then

self:updateProperty("value", false)

end

mqtt.Client.subscribe can also accept many topics, i.e. mqtt.Client.subscribe(topics, options)

Parameters

- - topics – (of type table) each item must be of either type:
    - {string topic, int qos} pair
    - string topic (qos defaults to the one passed in the options)
  - options – (optional) is a table with following members (all are optional):
    - qos – (of type number) the desired quality of service level for subscription. Defaults to 0. See also QoS enum.
    - callback – function called when the disconnect attempt is complete.

Returns packet ID – a unique identifier used to identify a message.

subscribed event – triggered when SUBACK is received from the server. Event arguments:

- - packetId – packet ID as returned by subscribe().
  - results – (of type table) the broker sends one return code for each topic/QoS-pair it received in the SUBSCRIBE message. So if the SUBSCRIBE message had 5 subscriptions, there will be 5 return codes to acknowledge each topic with the QoS level granted by the broker. If the subscription was prohibited by the broker (e.g. if the client was not allowed to subscribe to this topic due to insufficient permission or if the topic was malformed), the broker will respond with a failure return code for that specific topic.
    
    Return Code Return Code Response
    
    0 Success – Maximum QoS 0
    
    1 Success – Maximum QoS 1
    
    2 Success – Maximum QoS 2
    
    -1 Failure

Return Code	Return Code Response
0	Success – Maximum QoS 0
1	Success – Maximum QoS 1
2	Success – Maximum QoS 2
-1	Failure

mqtt.Client.unsubscribe(topics, options)

Unscubscribes from the topic(s).

Parameters

unsubscribed event – triggered when UNSUBACK is received from the server. Event arguments:

- - packetId – packet ID as returned by unsubscribe().

Returns packet ID – a unique identifier used to identify a message.

mqtt.Client.unsubscribe(topics, options)

Same as above but accepts multiple topics (array of strings).

Parameters

unsubscribed event – triggered when UNSUBACK is received from the server. Event arguments:

- - packetId – packet ID as returned by unsubscribe().

Returns packet ID – a unique identifier used to identify a message.

mqtt.Client.publish(topic, payload, options)

Publishes a message, the broker forwards the message to the interested clients (topic filtering).

Parameters

- - topic – (of type string) the topic name
  - payload – (of type string) the actual content of the message
  - options – (optional) (of type table) members (all are optional):
    - qos – (of type number) the desired quality of service level for this message. Defaults to 0. See also QoS enum.
    - retain – (of type bolean) determines if the message will be saved by the broker for the specified topic as last known good value.
    - callback – function called when the disconnect attempt is complete.

onpublished event – triggered when PUBACK is received from the server.

- - packetId – packet ID as returned by publish().

Example

function QuickApp:publishTurnedOn(id)
  self.client:addEventListener('published', function(event) self:onPublished(event) end)    
  self.client:publish("lights/" .. tostring(id), "ON")
end

function QuickApp:onPublished(event)
    print("onPublished:", json.encode(event))
end

function QuickApp:publishTurnedOn(id)

self.client:addEventListener('published', function(event) self:onPublished(event) end)

self.client:publish("lights/" .. tostring(id), "ON")

end

function QuickApp:onPublished(event)

print("onPublished:", json.encode(event))

end

Message Event

message event is triggered when broker forwards a message published by one of the clients to this client. Event arguments:

- - topic – (of type string) topic name
  - payload – (of type string) the actual content of the message
  - packetId:int (nil for QoS=0)
  - qos – (of type number) the desired quality of service level for this message. Defaults to 0.
  - retain – (of type bool) determines if the message was saved by the broker for the specified topic as last known good value.
  - dup – (of type bool) indicates if the message is a duplicate and is re-sent because the other end didn’t acknowledge the original message.

Error Event

error event is triggered when an error occurred in the channel. Event arguments:

- - code – number with error code

Links

MQTT 101 – How to Get Started with the lightweight IoT Protocol

MQTT Essentials

Online client for quick testing

Quality of Service levels explained

MQTT Specification v3.1.1

April 9, 2020 18307 Tutorials Lua, Quick Apps

Total 10 Votes:

Tell us how can we improve this post?

Captcha: + = Verify Human or Spambot ?

← Go back to browsing Knowledge Base articles

Comments are closed.

MQTT features and concept

Callback vs. Event

Quality of Service

mqtt.Client.connect(uri, options)

Parameters

Example

mqtt.Client.disconnect(options)

Parameters

mqtt.Client.subscribe(topic, options)

Parameters

Example

Parameters

mqtt.Client.unsubscribe(topics, options)

Parameters

mqtt.Client.unsubscribe(topics, options)

Parameters

mqtt.Client.publish(topic, payload, options)

Parameters

Example

Message Event

Error Event

Links

Tell us how can we improve this post?

Related articles: