====== MQTT Finder  ======

<WRAP center round tip 100%>
== Compatibility ==

MQTT Finder and MQTT Finder data are available starting with LoxBerry V3.0. 
</WRAP>

LoxBerry's MQTT Finder is a permanent MQTT "sniffer" that collects all mqtt data from your broker.

For users, a simple user interface allows to explore and inspect mqtt data.

For developers, it allows permanent access to all mqtt data without creating a listening service/daemon and subscriptions.

====== MQTT Finder user interface ======

{{entwickler:entwicker_tipps_und_tricks:1290043549.png?w=500}}

MQTT Finder is available on every LoxBerry using the url http://loxberry/admin/system/mqtt-finder.cgi (inside the MQTT widget).

From within a plugin, MQTT Finder is thought to be opened in a new browser tab/window without leaving your plugin, therefore it also supports opening it without panels (see below).

Entries shown in green color got updated in the last 60 seconds. 

==== Use Subscription syntax for filter ====

{{entwickler:entwicker_tipps_und_tricks:1290043550.png?w=350}}

Enabling this checkbox, your search need to correspond to the mqtt subscription syntax with __exact match__.  The mqtt jokers **+** and **#** are possible.

This allows to test your subscriptions and see, what data would arrive with your subscription.

==== Open MQTT Finder without panels (nopanels) ====

''%%http://loxberry/admin/system/mqtt-finder.cgi%%''**''%%?nopanels=1%%''**

This can be combined with pro-allocated search query and subscription filter (see next).

==== Pre-Allocate search query and subscription filter (mostly for developers) ====

As plugin developer, you have the possibility to pre-define the search field by a query parameter

''%%http://loxberry/admin/system/mqtt-finder.cgi%%''**''%%?q=mytext%%''**

To enable the subscription exact matching, add parameter **e** (no value needed):

''%%http://loxberry/admin/system/mqtt-finder.cgi?q=mytext%%''**''%%&e%%''**

Don't forget to uri-escape your search string.

====== MQTT Finder data ======

MQTT Finder is a service (process name is mqttfinder.pl) that is executed on every boot-time, and subscribes the # topic.

All incoming data - published or retained - are collected and stored every second to the ramdisk file /dev/shm/mqttfinder.json.

Example data structure:

<code json>
{
   "incoming" : {
      "awattar/advise/Geschirrspüler/device" : {
         "p" : "Geschirrspüler",
         "t" : 1636282811.93135
      },
      "awattar/advise/Geschirrspüler/deviceuid" : {
         "p" : "5d1c26de-50f5-493c-bbef-1b0f9e259ee1",
         "t" : 1636282811.93228
      }
   }
}
</code>

The file contains an object list called **''%%incoming%%''**, that contains one object per received topic.

Each topic object contains the properties **''%%p%%''** (=payload) and **''%%t%%''** (=last received epoch timestamp). Payloads are "as-is", therefore it may contain a json payload (that is correctly escaped to be parsed by a json library).

Accordingly to the timestamp, topics are removed from the file if nothing was received for the last 7 days. Data cleanup takes place every 60 minutes.

When accessing the file /dev/shm/mqttfinder.json, you should consider to implement a shared file lock, and error handling, as the file might get currently written during your try to access. You might implement a retry after some milliseconds if first try fails.

Please consider:

  * As the file resides on the ramdisk, after a LoxBerry reboot the file might not yet be available, or might be (nearly) empty.
  * Data stay in the file, also in the case that the device is not be present anymore. Data are dropped out after 7 days. Use the timestamp to evaluate the actuality, or e.g. the LWT of the device.   
 

====== MQTT Finder Logfile ======

The MQTT Finder Logfile (available via Log Manager, "MQTT") lists every incoming mqtt message. This can help to identify, if mqtt devices send data to the broker.

{{entwickler:entwicker_tipps_und_tricks:1290043506.png?w=700}}