.. _mqtt:

MQTT Interface
==============

`MQTT <https://mqtt.org/>`__ is a publish-subscribe protocol to transport arbitrary data between clients.
MQTT clients connect to a server (called MQTT broker) and publish and/or subscribe to topics,
identified by an (almost) arbitrary name.
Topics are often structured in a hierarchy using slashes, for example ``neobotix/platform/mpo-700-1/navigation/map_pose``.

PlatformPilot can be set up to act as an MQTT client to a MQTT broker, translating messages from and to internal topics.
All sent messages will be JSON objects, except possibly the `Last-Will` message.
All messages that should be received also have to be JSON objects.


Client
------

In your :ref:`configuration <Configuration>` folder add or append a file named ``mqtt_proxy_list`` to contain
a list of the MQTT proxies that should be started. Each one will be one MQTT client (usually you only need one per broker).

.. code-block:: javascript

	["MQTT_Proxy_1", "MQTT_Proxy_2", ...]

The individual options can be set in the corresponding configuration file, e.g. in ``MQTT_Proxy_1.json``.
The only necessary setting is the broker address, but you probably also want to specify
the client ID and the exported topics.
Here is an example configuration:

.. code-block:: javascript

	{
		"address": "tcp://10.1.30.42:1883",
		"client_id": "nbx-pp-1",
		"export_map": [
			["platform.system_state", "neobotix/<robot-name>/platform/system_state"],
			["platform.emergency_state", "neobotix/<robot-name>/platform/emergency_state"]
		],
		"export_map_ex": [
			["platform.info", {
				"topic": "neobotix/<robot-name>/platform/info",
				"retained": true
			}]
		],
		"last_will": {
			"topic": "neobotix/<robot-name>/disconnect",
			"message": "Apparently, an unexpected disconnect happened..."
		}
	}


Find all configuration options at :ref:`vnx.mqtt.Proxy`.