===============
MQTT PubSub API
===============

MQTT PubSub client is used to connect to MQTT broker, subscribe to topics, publish data.
It can be used in combination with OPC UA server to listen changes in nodes and publish data to MQTT broker.
Also it is possible to use it to publish data to MQTT broker without OPC UA server. In this case
you'll need to set data manually.

MQTT Client constructor
~~~~~~~~~~~~~~~~~~~~~~~~

.. function:: ua.newMqttClient()
              ua.newMqttClient(config)
              ua.newMqttClient(config, uaServer)
              ua.newMqttClient(config, model)

  Create an instance of MQTT client.
  MQTT client is used to connect to MQTT broker, subscribe to topics, publish data.

  :param config: MQTT client configuration. if not provided then default configuration will be used.

  :param uaServer: OPC UA server instance.
                   If provided, MQTT client can connect to nodes and listen value changes.

  :param model: OPC UA model. If provided will use it for encoding/decoding datastructures.

  :return: MQTT client instance.

  If uaServer and model not provided then MQTT client then will be loaded only base OPCUA model. Thus will be possible
  to encode/decode only base OPCUA data types.

MQTT Connect
~~~~~~~~~~~~

.. function:: uaMqtt:connect(endpointUrl, tranportProfileUri, <connectCallback>)

  Connect to MQTT broker.

  :param endpointUrl: OPCUA Endpoint URL
  :param tranportProfileUri: OPCUA Transport Profile URI. Defines encoding of the messages:

                             * ua.TranportProfileUri.MqttBinary
                             * ua.TranportProfileUri.MqttJson

  :param connectCallback: Callback function

.. code:: lua

  local function connectCallback(status)
    print("Connected to MQTT broker")
  end

  uaMqtt:connect("mqtt://localhost:1883", ua.TranportProfileUri.MqttBinary, connectCallback)

MQTT subscribe
~~~~~~~~~~~~~~

.. function::  uaMqtt:subscribe(topic, messageCallback)

    Subscribe to MQTT topic.

    :param topic: MQTT topic
    :param messageCallback: Callback function


.. function:: messageCallback (topic, message)

    Callback function for MQTT message.

    :param topic: MQTT topic
    :param message: Decoded OPCUA message


MQTT publishing
~~~~~~~~~~~~~~~

.. function:: uaMqtt:createDataset(fields, datasetId)

    Create dataset which will describe message content to publish.

    :param fields: Array of Fields. Each field is a table with next fields:

                    * **name**: Field name. Defines field name in the dataset which will be used in JSON format and in metadata for binary messages.
                    * **nodeId**: nodeId in OPUCA server instance which changes will be listened and published.

                  The order of fields will be preserved in published MQTT payload messages.

    :param classId: Class ID. Is used to distinguish datasets at subscriber side.


.. function:: uaMqtt:setValue(datasetId, fieldName, dataValue)

  Set field value in the dataset.

  :param datasetId: Dataset ID
  :param fieldName: Field name
  :param dataValue: Field value

.. function:: uaMqtt:publish(dataTopic, publisherId)

    Publish dataset. Will forcibly publish dataset with all the changes fiels.
    if not

    :param dataTopic: Data topic
    :param publisherId: Publisher ID


.. function:: uaMqtt:startPublishing(dataTopic, publisherId, periodMs)

    Start publishing dataset periodically with changed fields.

    :param dataTopic: Data topic
    :param publisherId: Publisher ID. string or numeric value.
    :param periodMs: Period in milliseconds

.. function:: mqttServer:stopPublishing()

    Stop publishing dataset.