(This article will be in English to reach all users, not only German speaking)

This is a step-by-step troubleshooting guide to get your mqtt data to the Miniserver.

You should try every proposal for itself, one by one, and check the result.

I assume, that the installation process of the MQTT Gateway plugin was successful (had no errors). If the installation process failed → Submit the full installation log. 

After the installation: Check the main page of the MQTT Gateway plugin. In the footer section you should see both MQTT Gateway and Mosquitto broker running:

• After a LoxBerry reboot, the webinterface starts up earlier than the Mosquitto services does. Wait up to about 5 minutes after LoxBerry reboot, if the daemon may come up.
• Check that you have selected "Use local Mosquitto broker" in the "MQTT Broker" section of the plugin. If this is not selected, the broker is not managed by the MQTT Gateway plugin.
• In the webif, enter the SecurePIN to see your credentials, and save the settings again. This triggers a retry to start Mosquitto.
• If it is still not running: Connect by SSH, su to become root, and try systemctl stop mosquitto and systemctl start mosquitto. Look for error messages.
• If it happens again, and you already have the latest version installed: Please report the error including version number, and the latest gateway logfile.

• Navigate to the log section and open the first log. Check for error messages.
• If you see errors and cannot manage to solve them, submit the full logfile.

Mosquitto and Gateway are running, but the Gateway sends warnings to the log, that it cannot connect to the broker.

• If "Use local Mosquitto broker" is enabled: 
  • Check the hostname and port, it should be localhost:1883
• If "Use local Mosquitto broker" is disabled:
  • Check the hostname and port, username and password of your remote broker
  • Try to ping the hostname on the shell, or try it with the ip address.
  • Some external brokers deny access without credentials.
  • Some external brokers deny access with username, but empty password.
• Check your subscriptions! Mosquitto immediately closes the connection when a syntax error occur in your subscriptions. 
  • An indicatior for this issue is the connection process in the logfile. On a syntax error with subscriptions, the Gateway logs in to the broker sucessfully, and also successfully sends its Last Will. Later, after subscribing, the Gateway warns about no connection.
  • Common syntax errors:
    • shellies# → wrong! shellies/# → correct 
    • fhem/+room/temperature → wrong! fhem/+/temperature → correct
    • espeasy/## → wrong! espeasy/# → correct
    • espeasy/#/temperature → wrong! espeasy/+/temperature → correct

Several ports are used around the gateway functionality. Here is a list of the default ports:

•  "Miniserver UDP Port" 11883 (UDP) is the port, the plugin is sending data to the Miniserver if sending via UDP is enabled. For UDP transmission, this port needs to be configured on your Miniserver at the Virtual UDP Input. MQTT→Plugin→Miniserver (UDP). 
• "Gateway UDP-In Port" 11884 (UDP) is the port where the plugin is listening on LoxBerry for incoming messages from the Miniserver. This provides the possibility, that Miniserver can send messages to MQTT devices. Miniserver→Plugin→MQTT
• Mosquitto Broker-Port 1883 (TCP) is the port, where the broker is listening to connections from MQTT devices. You need to configure this port (together with hostname/ip of LoxBerry) on your MQTT devices (like Tasmota, ESP-Easy, Shelly etc.)
• Mosquitto Broker-Port 8883 (TCP) is the secured (encrypted) MQTT broker port. Currently port 8883 is configured to use TLS-PSK. The connecting client needs to support TLS-PSK with TLS at least v1.2. The PSK is shown in plugins credentials settings. It is automatically created and cannot be changed in the webif.   
• Mosquitto Broker-Port 9001 (TCP) is the MQTT Websocket port. MQTT Websocket clients can connect to this port with the same credentials. TLS currently is not supported. The WebSocket port is configurable in the Setting tab. 

• On your MQTT device, check if you have entered <loxberry-hostname>:1883 as the mqtt broker address. 
• Try to use LoxBerry's IP <loxberry-ip>:1883 if the <hostname> does not work.
• Double-check that you have entered exactly the username and password that are listed in the plugin ui. Both are case-sensitive. 
• Check your ip settings! Is your MQTT device in the same network/subnet as LoxBerry?
  • Can you ping the MQTT device from LoxBerrys shell? Can you ping LoxBerry from the MQTT device? 
  • If you have set static ip in LoxBerry and/or device, revert both back to DHCP. 
• If the device supports an encrypted connection, disable encryption and retry.
• Do not try the ports 11883 and 11884 because they are wrong (see the port list in the MQTT Gateway section). Be sure you have used 1883. 
• If you require that your values are saved on the broker, set the "retain" flag in your device. Without retain, values are sent but not stored on the broker. 

In the internet you find many scripts that connect non-mqtt devices to an MQTT broker.  Depending of their functionality, they may need to be called periodically, or directly run as a daemon.

• For the broker connection:
  • For hostname use loxberry (or your LoxBerry hostname, if you have that changed, or the ip address of LoxBerry if your device does not connect) 
  • For port use 1883
  • For authentication use username and password from the plugins web interface
  • Do not enable encryption
• If your script does not support authentication, you may disable authentication on the Mosquitto broker, by setting username and passwort empty in the plugins webinterface. Keep in mind, that changing the credentials here, needs to reconfigure all mqtt devices that already used that credentials.
• If you have questions regarding your script, ask the developer or developer community of that script, or you may open an own topic in loxforum.com. 

Depending on the send type, the configuration in Loxone Config is different. 

• Use sending by HTTP or by UDP. You shouldn't use both because it doubles the transfer load on the Miniserver.
• I suggest to use HTTP instead of UDP. It is easier to configure in Loxone Config, and creates less CPU stress on the Miniserver. Only if the transferred data require to use special command recognitions, use UDP.
• If you receive data in the Incoming Overview and Miniserver, but they look like this { "firstvalue": "123", "secondvalue": "345" } (with curly brackets), check to have Expand JSON data enabled on the plugins Settings page.

• In the LoxBerry "Miniservers" widget, check that your Miniserver credentials are still working (with the "Check authentication" button).
• Keep in mind: During normal operation, only changes are submitted to the Miniserver.
• The Virtual Input name must exactly match the listing in the Incoming Overview.
• Virtual Inputs in Loxone only accept numbers.
• Virtual Text Inputs in Loxone also accept text.
• In the properties of a Virtual Input, check the following settings:
  • Use as Digital Input: Disabled
  • Check the validation settings, that your mqtt values are inside the validation boundaries.
  • Check the permissions of the Virtual Input in Loxone Config. Every input can have individual permissions. Your connecting user needs to have permissions to this Virtual Input/Virtual Text Input.
• If your own values do not arrive, first test with the provided loxberry_mqttgateway_keepaliveepoch value. It is a Linux Epoch timestamp and is updated every minute. Also edit the validation boundaries in the Config properties.
• If this timestamp works, check that your value is really a value (and not a text).
• Use conversions in the plugin to convert text to values, if you get status texts from your MQTT device. Later, use a Status block in Loxone Config, to convert numbers back to text.
• Values are cached - only changes are sumitted. To force retransmitting values, press the "Resend data to Miniserver" button in the webif. This forces to send incoming values again. 

• Check the selected Miniserver and "Miniserver UDP port" you have set in the plugin web interface. The choosen port is the incoming port on your Miniserver.
• Use the Loxone UDP Monitor to see if values are submitted. At least the loxberry_mqttgateway_keepaliveepoch should be seen every minute.
• If no values are subitted, open the plugin log to check for errors and warnings.
• If values come in, create Virtual Input Commands with command recognitions to get the values. See Loxone documentation how command recognition is working. You may use the plugin Command Recognition - Befehlserkennung to support you with command recognitions.

• If your MQTT device always submits the same value (e.g. a buttons sends "pressed" for each button press), no change is identified by the Miniserver. For this case, enable "Reset-After-Send" in the Incoming Overview, with "Advanced Table Information" enabled. This will send an additional 0 after each submission (to reset the Miniserver input).
• If your device sends json data (values are in {} curly braces), enable "Expand JSON data". The json then is "expanded" to single data values.
• If your devices sends a lot of data, but you only need some of them, set the "Do not forward" flag in the Incoming Overview with "Advanced Table Information" enabled. These values aren't forwarded to the Miniserver, and therefore reduces cpu load on the Miniserver.   

On every issue you cannot solve yourself, submit the full plugin log. If errors occur on your mqtt device, submit the log of your device. Explain what you have already tried.