MQTT

From SweepMe! Wiki
Jump to navigation Jump to search

The MQTT module allows to connect to a MQTT broker which is server that reminds the last values of so-called topics. Whenever new data of a certain topic arrives, old data will be overwritten. You can publish data to actualize the current values of the MQTT broker. Furthermore, you can subscribe certain topic and the MQTT broker will inform you whenever related data changes.

Using MQTT, you can greatly extend the functionality of the SweepMe! main program. The MQTT basically allows to break out of SweepMe! and to handle data outside the program without interfering with the measurement itself. For example, you can create web applications to monitor the status of your measurement, send emails after the measurement has finished or forward your data to a database where it is automatically stored during the measurement.

Graphical user interface

Mode

Select whether you like to use the MQTT module to subscribe or to publish. At the moment, only 'publish' is supported and 'subscribe' will be added on demand.

Host

Enter the IP address of your MQTT broker, can be 'localhost' if the MQTT broker runs on your machine. Can be an IPv4 address like '192.168.0.102' or any other combination of numbers. It also can be a domain name.

Port

Most MQTT brokers work with port 1883. Contact the administrator of the MQTT broker if this port does not work.

User

Enter a user name if access to the MQTT broker is restricted to a certain number of people.

Password

If a user name is given, you also have to type in your password that is registered at MQTT broker.

Topic

Enter the main topic that is used by the MQTT module. It will be prepended to all sets of data. Please read how to publish or to subscribe. You can create subtopics like this: "main/sub/subsub" Leading and trailing "/" will automatically handled correctly. You do not need to worry.

Quality

The MQTT protocol supports three quality of server (qos) levels that describe how your data is exchanged with the MQTT broker.

  • 0 - at most once -> Data is sent one time. If it does not work no further action is done. Use this mode to send data that is measured frequently where loss of data is acceptable or if you are sure that you have proper connection.
  • 1 - at least once -> Date is sent again, if there is no acknowledgement from the server. Thus, the same data might be sent several times. Use this mode if you like to make sure that your data is simply actual, but you do not matter if it is sent multiple times.
  • 2 - exactly once -> This level tries to make sure that your data reached the MQTT broker by some kind of handshaking between the MQTT server and the client to send it exactly once. Use this mode if you have to make sure that your data arrives and exactly once. This could be the case if you use a MQTT broker to save data to a database and you would like to prevent multiple entries, but still you have to make sure that no data is lost.

Retain

Only available for publish. Values with retain are stored on the MQTT broker as last good values. Whenever a client subscribes, such a value will immediately be sent.

Publish

To publish data with SweepMe! just select the variables that you would like to send. The final topic that is sent to your MQTT broker is automatically composed out of the general topic you inserted in the field 'Topic' and the given subtopic of each selected variable. Right-click on a variable to copy its current topic.

Subscribe

Subscribe to topics of an MQTT broker. The returned values of the MQTT module are the last known values that have been changed by a message from the MQTT broker.

MQTT broker

A free, open-source MQTT broker is mosquitto (link) provided by the Eclipse foundation: The MQTT broker is a server that can run on your machine so that you access it as 'localhost'. This is typically the case if you like to test something. Once you go to production mode, the MQTT broker will run on a central computer, e.g. a raspberry pi, and you need to know the correct IP address of this computer.

A MQTT broker for testing purposeses can be found here: https://test.mosquitto.org/ It is not recommended to send sensitive data as everybody can access the server worldwide.

Node-RED

Node-RED (link) can be used to create browser based user interfaces to handle data received from the MQTT broker.