The MQTT Gateway offers interfaces and helpers for plugins. In your plugin, you can make use of the MQTT Server configuration, the UDP interface and your own subscriptions, conversions and settings. You can ship your plugin with settings read by the MQTT Gateway, or can create configurations on-the-fly in your plugin, that is, also on-the-fly, read and used by the MQTT Gateway.

This is an use-case overview to articles with detailed information.

Use LoxBerry::IO::mqtt_connectiondetails (Perl) to get host, port and the credentials of the configured MQTT Server. With the shipped lib Perl Modul Net::MQTT::Simple (it's a modified version of Net::MQTT::Simple for LoxBerry), then you can connect to the MQTT Server.

Use LoxBerry::IO::mqtt_connectiondetails (Perl). It's return hash includes the UDP port to connect to the MQTT Gateway. With the UDP interface described here (MQTT Gateway - HTTP- und UDP-Interface), you can publish messages to the MQTT broker in a very easy way by UDP.

If you fully want to connect to the MQTT Server, we recommend Perls library Net::MQTT::Simple, that is included with LoxBerry (use Net::MQTT::Simple). 

1. Use LoxBerry::IO::mqtt_connectiondetails to check/aquire the MQTT Server settings.
2. Connect to the MQTT Server by the Net::MQTT::Simple library.

Use mqtt_connectiondetails (PHP) to get host, port and the credentials of the configured MQTT Server. With the shipped lib phpMQTT.php (it's an external MQTT library, included in LoxBerry's lib path) you can connect to the MQTT Server.

Use mqtt_connectiondetails (PHP). It's return array includes the UDP port to connect to the MQTT Gateway. With the UDP interface described here (MQTT Gateway - HTTP- und UDP-Interface), you can publish messages to the broker in a very easy way by UDP.

If you fully want to connect to the MQTT Server, we recommend PHP's library phpMQTT.php that is included with LoxBerry (require_once "phpMQTT/phpMQTT.php"). 

1. Use mqtt_connectiondetails to check/aquire the MQTT Server settings.
2. Connect to the MQTT Server by the phpMQTT.php library.

Starting with MQTT Gateway 2.0 (Release) the MQTT Server settings are provided directly in LoxBerry's main configuration file, general.json. See the Mqtt section in general.json for details.

We've a Python sample implementation here: https://github.com/mschlenstedt/Loxberry/blob/master/libs/pythonlib/sample_code/mqtt_credentials.py

To get LoxBerry's home, read the global system environment variable $LBHOME - on original LoxBerry, this is /opt/loxberry. 

1. Open and json-parse $LBHOME/config/system/general.json
2. Connection settings and credentials are provided in
   • Mqtt.Brokeruser
   • Mqtt.Brokerpass
   • Mqtt.Brokerhost
   • Mqtt.Brokerport
3. Some further rules for parsing:
   1. If the base object "Mqtt" is not defined, MQTT Gateway is not installed (LoxBerry before V3.0)
   2. If Brokeruser is empty, the broker has anonymous access enabled.
   3. If Brokerpass is empty, the broker has user login without password enabled.
   4. Brokerhost and Brokerport are always set - you don't need to fallback to localhost or a default port

Brokerport is the unencrypted MQTT TCP port without TLS.

To get LoxBerry's home, read the global system environment variable $LBHOME - on original LoxBerry, this is /opt/loxberry. 

1. Open and json-parse $LBHOME/config/system/general.json
2. The MQTT Gateway UDP port is 
   • Mqtt.Udpinport
3. Create a UDP outbound socket to localhost:<Udpinport>
4. With the UDP interface described here (MQTT Gateway - HTTP- und UDP-Interface), you can publish messages to the broker in a very easy way via UDP.

Your plugin can set subscriptions, conversions and the setting "resetAfterSend" (= send the value followed by 0) in the MQTT Gateway during plugin installation and during your plugin run-time. This is done by textfiles in your config directory. For the user, plugin-injected conversions and subscriptions are shown read-only below the normal conversions/subscriptions.

This method "injects" subscriptions to the MQTT Gateway.

With plugin installation: Place a file "mqtt_subscriptions.cfg" into your config directory in the plugin zip. 

During runtime: Place a file "mqtt_subscriptions.cfg" into your /opt/loxberry/config/plugins/<yourplugin>/ directory. 

The file is a textfile. Every line represents a subscription. Invalid subscriptions are filtered during runtime of the MQTT Gateway and are logged to the log of the MQTT Gateway.

This method "injects" conversions to the MQTT Gateway.

With plugin installation: Place a file "mqtt_conversions.cfg" into your config directory in the plugin zip. 

During runtime: Place a file "mqtt_conversions.cfg" into your /opt/loxberry/config/plugins/<yourplugin>/ directory. 

The file is a textfile. Every line represents a conversion. Invalid or duplicate conversions are filtered during runtime of the MQTT Gateway and are logged to the log of the MQTT Gateway.

After changing "mqtt_conversions.cfg", the update will be adopt immediately.

This method "injects" the resetAfterSend setting to the MQTT Gateway for specific topics. 

With plugin installation: Place a file "mqtt_resetaftersend.cfg" into your config directory in the plugin zip. 

During runtime: Place a file "mqtt_resetaftersend.cfg" into your /opt/loxberry/config/plugins/<yourplugin>/ directory. 

As the MQTT Gateway extracts the topic tree and json data to a flat string linked with the underscore (_), the list of topics require to use the underscore symbol:

Example:

Topic nuki/19283453 JSON data { "lockState" : 3 } expands to nuki_19283453_lockState

Therefore, place a line into the mqtt_resetaftersend.cfg:

nuki_19283453_lockState

This will enable resetAfterSend for this dataset.