MQTT Callbacks

With Callbacks Lua Scripting can be used to pre-process incoming and outgoing data or to create custom actions which are triggered when certain MQTT related events occur. Action Callbacks (On Connect, On Disconnect and On Delivery') defined on Datasource level apply to the Datasource object itself while Pre-processing Callbacks (Preprocess Outgoing and On Message Receive) on the same level apply to all subordinate IO-Items. Individual Callbacks on IO-Item objects allow specific data pre-processing and actions for each individual IO-Item.

By default the respective Callback properties provide empty functions, illustrating the parameter profiles.

General Callbacks

General Callbacks are located in the Callbacks section of the MQTT Datasource object.

Custom Actions For Connection Establishments

The script in the On Connect property is executed whenever a connection between the Datasource object and an MQTT Broker can be (re-)established and can be used to inform the system about the state of the connection to the MQTT Broker.

return function(topics)

end

General Pre-Processing of Outgoing Messages

The script in the Preprocess Outgoing property is executed whenever data is to be sent to the MQTT Broker. It can be used to modify the payload before it is sent to the MQTT Broker.

return function(guid, mid, topic, payload, qos, retain)

  -- Modify the payload here
  local modified_payload = modify_payload(payload)

  return guid, mid, topic, modified_payload
end

General Custom Actions For Confirmed Delivery of Sent Messages

The script in the On Message Delivery property is executed whenever the MQTT Broker confirms that it has received a message from the Datasource.

return function(guid, mid, topic, payload, qos, retain)

end

General Pre-Processing of Incoming Messages

The script in the On Message Receive property is executed whenever the system receives data from the MQTT Broker. Scripts located in this property can be used to modify the payload before it is forwarded to the IO items.

local json = require"rapidjson"

return function(guid, mid, topic, payload, qos, retain)
  local targetObjectPath = nil -- the subscriber IO-Item itself will be used
  local vqt = json.decode(payload)
  return targetObjectPath, vqt.V, vqt.Q, vqt.T
end

Custom Actions For Connection Ends

The script in the On Disconnect property is executed when the connection between the Datasource object and the MQTT Broker is interrupted and can be used to inform the system about the state of the connection to the MQTT Broker.

return function()

end

Individual Pre-Processing & Individual Custom Actions

Besides the general Callbacks which are defined on Datasource level and applied to all subordinate IO-Items, also specific Callbacks can be defined in the properties of each individual IO-Item.

Individual Pre-Processing of Incoming Data

MQTT Subscriber IO-Items can process incoming data individually before it is stored in the system. To automatically apply a Lua script to data received by a specific Subscriber Item, enter the script in the On Message Receive property which is located in the Item Type > Subscriber Properties properties compound of this IO-Item.

Pre-processing incoming data on IO-Item level takes place after the data was passed on from the Datasource object, where it may already have been pre-processed on Datasource level after it was received from the MQTT broker.

Here is an example for how VQT data is extracted from a JSON input:

local json = require"rapidjson"

return function(guid, mid, topic, payload, qos, retain)
	local targetObjectPath = nil -- the subscriber IO-Item itself will be used
  local vqt = json.decode(payload)
  return targetObjectPath, vqt.V, vqt.Q, vqt.T
end

Individual Pre-Processing of Outgoing Data

Data pre-processing for MQTT Publisher IO-Items can be similarly implemented as a Lua function in the Preprocess Outgoing Message property hosted in the Item Type > Publisher Properties property compound of the respective IO-Item.

Pre-processing outgoing data on IO-Item level takes place before the data is passed on the Datasource object, where it can then be further pre-processed before it is sent to the MQTT broker.

return function(guid, mid, topic, payload, qos, retain)

  -- Modify the payload here
  local modified_payload = modify_payload(payload)

  return topic, modified_payload, qos, retain
end

Individual Custom Actions for Confirmed Delivery of Sent Messages

The On Message Delivery property in an MQTT Publisher IO-Item’s Item Type > Publisher Properties property compound allows to provide a Lua function which is executed every time the MQTT Broker confirms that it has received the data from this specific Publisher IO-Item. There are no values which can be returned from this function.

return function(guid, mid, topic, payload, qos, retain)

end