(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:
Mosquitto is not 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 including version number, and the latest gateway logfile.
MQTT Gateway not running
- 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.
MQTT Gateway warns about no connection to broker
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.
- 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 an 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:
Ports of the MQTT Gateway
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.)
MQTT device cannot connect to broker
- 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.
- If the device supports a 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 want, that your values are saved on the broker, set the "retain" flag on your device. Without retain, values are sent but not stored on the broker.
MQTT gateway/bridge scripts
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.
General connection settings
- For the broker connection:
- For hostname use loxberry (or your LoxBerry hostname, if you have that changed)
- 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.
General connection settings
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.
Sending via HTTP
- 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.
- 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 you 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 "Save and Apply" button in the webif. This forces to send incoming values again.
Sending via UDP
- 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 works. You may use the plugin Command Recognition - Befehlserkennung to support you with command recognitions.