Skip to main content

MQTT - Unity interface

[!WARNING] This documentation is set to be partialy merged with the API documentation for Unity.

[!WARNING] This package does not allow for certificate validation.

Project owner: Yann van Eijk

Project description

This repository contains the scripts needed within Unity to create an interface between MQTT and Unity. Its main functionality is to receive and sent real-time messages from topics on the MQTT Broker. These messages are processed within Unity as strings, for other types use TryParse.

Installation

The MQTT package is part of the 'DT lab Unity interface package'. For a full installation guide, please refer to...

MQTT broker connections

A connection to the MQTT broker can be established using the MQTT editor window. This window can be found under the header Tools -> EAISI Digital Twin Lab -> MQTT editor. A new window should pop up next to the Inspector window.

In this window, the following parameters need to be set:

Variable Type Description Optional/ Required
TCPServer serveradress String Hostname or IP adress of MQTT Broker. Required
Port String Port number of MQTT on broker. Required
Use Credentials Boolean Some MQTT brokers require user credentials for connections. If this is the case for the broker you want to connect to, tick this box. Optional (Check broker)
Use Encryption Boolean Some MQTT brokers require an encrypted connection. If this is the case for the broker you want to connect to, tick this box. Optional (Check broker)
Username String Username of account set at MQTT broker. Optional (see Use Credentials)
Password String Password of account set at MQTT broker. Optional (see Use Credentials)
Topics List<String> List of topics to subscribe to. All subscription topics used in the Unity project should be declared here. Optional (Required for subscription functionality)
Connect to MQTT broker at runtime Boolean Disables editor time connection and enables connection upon entering runtime. Only enable this setting after testing the connection in editor time. Optional

Upon the initial opening of the editor window, the TCPServer serveradress and Port variables are already set. This allows the user to quickly check if a connection to test.mosquitto.org can be established. To test this, click the gray connect button on the bottom the MQTT editor window. In the console, a debugging message should pop up stating Connected to: test.mosquitto.org:1883. This indicates that the package is working as intended.

Workflow

  1. Setup MQTT broker. If you already have an account and password provided by the Digital Twin Lab or if you already setup your own broker, go to step 2. For certain projects it is possible to make use of the MQTT broker of the Digital Twin Lab. If you want to make use of the MQTT broker of the Digital Twin Lab, but dont have credentials yet, please contact us via e-mail.
  2. Open the MQTT Editor Window via Tools -> EAISI Digital Twin Lab -> MQTT editor in the Unity Editor. A new window should pop up next to the Inspector window.
  3. You can test the library by clicking the Connect button on the bottom of the MQTT editor window without changing any of the windows parameters. This only tests if the interface can connect to a MQTT broker, no messages are relayed. A message stating Connected to: test.mosquitto.org:1883 should pop up in the Console window within Unity. Clicking Disconnect disconnects the Unity client from the MQTT broker, indicated but the message Disconnected from: test.mosquitto.org:1883.
  4. Now, the connection to the desired MQTT broker can be established. Make sure to execute step 1 of this workflow.
  5. Fill in the parameters in the MQTT editor window as described in MQTT broker connections according to the settings of your MQTT broker. Click Connect, if no connection is established, an error message will pop up in the Console. I.e. SocketException: Could not resolve host 'test.mosquittofalse.org', indicating the wrong TCPserver adress. Any error concerning a MqttCommunicationTimedOutException indicates a wrong port. If a connections is established, click Disconnect.
  6. If applicable, you can test receiving messages from the MQTT broker by adding the subsciption topics in the Topics list. You can do so by clicking the + button and entering the full path to the variable you want to receive in Unity. After hitting Connect, the topic and value should be displayed in the Received header at the bottom of the MQTT editor. Click Disconnect.
  7. If applicable, you can test sending messages to the MQTT broker from Unity. After clicking Connect, a Publish header should be visible right under the Disconnect button. For the Topic value, enter the path of the topic you want to publish to. For the Message value enter the message you want to publish. To check if the messages is received, check the MQTT broker or any MQTT client subscribed to the publishing topic. Click Disconnect.
  8. For receiving messages in runtime, make sure to fill in all topics you want to subscribe to for your Unity project in the Topics header and check the Connect to MQTT broker upon entering runtime box. Once this box has been ticked, no changes can be made to the MQTT editor window. Unity will automatically connect to the MQTT broker and subscribe to the subscription topics. In order to read these received messages in runtime, you could do something like the DataManager script attached to the Data Object prefab which can be found under the folder .../DT lab/MQTT. This script subscribes to all topics present in the subscription topic list of the editor window vai the MessageManager. It stores these values in a public string each time the value changes, and uses the Update() functionality to display them in the Inspector window. In short, to receive data from a topic in runtime, your MonoBehaviour script should call: 
    
 MessageManager.Instance.SubscribeToTopic(topic, HandleFunction);
    Where topic is the subscription topic, and HandleFunction is the function that gets called when the value on the topic gets updated. An example of this is shown below. 
    
 private void HandleFunction(string topic, string message)
 {
     SubscribedTopics[topic] = message;
 }
    This function stores the received message of the topic in the dictionary SubscribedTopics. But you can define your own function if desired.
  9. Publisihing in run time can be done by calling the function below. 
    
 MQTT_lib.PublishToTopic(TopicToPublish, message.ToString());
    TopicToPublish is a string of the full path of the topic you want to pulbisch to. message is the message you want to publish. Make sure this message is converted to either a string or JSON format.
  10. You can reiterate steps 6 to 9 can be iteraly repeated to get the desired data interface between Unity and the MWTT broker.

Development

  1. Code needs to be reviewed.
  2. Build needs to be checked.
Back to top