Skip to end of metadata
Go to start of metadata

The MQTT Gateway plugin offers interfaces and helpers for other plugins. In your plugin, you can make use of the broker configuration, the UDP interface and your own subscriptions, conversions and settings. You can ship your plugin with settings read by the MQTT Gateway plugin, 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-Cases for Perl

Read broker settings and credentials

Use LoxBerry::IO::mqtt_connectiondetails (Perl) to get host, port and the credentials of the configured MQTT broker. 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 broker.

Get UDP in-port of MQTT Gateway plugin to publish messages via the MQTT Gateway

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 broker in a very easy way.

Create connection to the MQTT broker to publish and subscribe

If you fully want to connect to the MQTT broker, 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 broker settings.
  2. Connect to the broker by the Net::MQTT::Simple library.

Use-Cases for PHP

Read broker settings and credentials

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

Get UDP in-port of MQTT Gateway plugin to publish messages via the MQTT Gateway

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.

Create connection to the MQTT broker to publish and subscribe

If you fully want to connect to the MQTT broker, 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 broker settings.
  2. Connect to the broker by the phpMQTT.php library.

Use-Cases for other languages (Python, Node.js, etc.)

Read broker settings and credentials

  1. Read the plugindatabase.json and search for the attribute 'name' or 'folder' containing "mqttgateway". From the json, read pluginid.directories.lbpconfigdir and remember it as <configdir>.
    → Not found? → MQTT Gateway not installed.
  2. Read <configdir>/mqtt.json to an object mqttconf
  3. mqttconf contains Main.brokeraddress (it contains host and port, and if no port assigned, you need to default to 1883)
  4. Read <configdir>/cred.json to an object credconf
  5. credconf contains Credentials.brokeruser and Credentials.brokerpass. Both may be empty or undefined, if the broker uses anonymous authentication.
  6. Connect to the broker with a MQTT library of your choice.

Get UDP in-port of MQTT Gateway plugin to publish messages via the MQTT Gateway

  1. Follow the steps 1 to 3 from above.
  2. The mqttconf contains Main.udpinport where the MQTT Gateway is listening for udp.
  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.

Inject subscriptions, conversion, resetAfterSend by your plugin

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.

Create plugin subscriptions during plugin installation or during runtime

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 plugin and are logged to the log of the MQTT Gateway plugin.

Create plugin conversions during plugin installation or during runtime

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 plugin and are logged to the log of the MQTT Gateway plugin.

Set "resetAfterSend" flag for a topic

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.


  • No labels