Widget FAQs
What’s the difference between Graph Widgets and Multi Graph Widgets?
Graph widgets are simple widgets that show a single graph of an MQTT topic. They can be customised to some extent, setting the update interval and amount of values the widget should show.
Multi graph widgets are very customisable widgets that can show multiple graphs in one widget. You can customise each graph, setting the broker, topic, graph color and other things. This allows you to do things like display all your temperature sensors in one widget or combine data from multiple brokers. There’s no limit to how many graphs can be added, but my recommendation would be a maximum of 5 or things get a bit out of hand.
What’s needed to get widgets to work?
There are some limitations to what widgets can do on iOS. There are also a few requirements that need to be met to get widgets to work with EasyMQTT.
The most important one is that the MQTT messages need to be retained (saved by the broker). iOS apps are not allowed to constantly be open in the background, so the messages need to be saved so the app can get the latest value whenever it’s allowed to fetch data by iOS
The message payload needs to either contain only the value (number) for the graph, or needs to be in JSON format for EasyMQTT to be able to read the data.
The value of the message needs to only contain a number and no additional unit of measurement or other text. Those can be defined later in the widgets.
How do I create a multi graph widget?
Multi graph widgets are created in the app. You can create them in either the Widgets tab or the Settings tab under Widgets.
Create a new widget, set a title and hit save
Select the new widget, it should show you a preview of the (empty).
The next step is to select/create the graphs to add to the widget. Tap Select Graphs.
On the next page you can select the graphs to add to your widget or hit the + button to create new graphs. See the chapter below for an explanation of all the settings.
The widget should now be ready, to check whether it’s working and receiving data you can press the Refresh button on the widget screen, which will immediately refresh it and fetch data from the topics
To actually use it as a widget you’ll have to add it to your Home screen. Long press on the screen and search the widgets for EasyMQTT, then scroll to the Multi graph widget.
Add the widget to the Home Screen and then edit it and select the widget you just created in the app
What do the different configuration parameters do?
Topic sets the topic the app should subscribe to when updating the widget/graph. Messages sent on this topic need to meet certain requirements (see above).
The property path is to point the widget towards where the temperature value of the topic is. In this example (I'm using zigbee2mqtt), the messages look like this:
{ "voltage" : 3005, "humidity" : 30.27, "temperature" : 20.260000000000002, "pressure" : 994, "battery" : 100, "linkquality" : 69 }
So for the widget to get to the temperature data, the property path is set to payload.temperature. If the sensor would publish only the temperature to the topic then you'd only have to set the property path to payload.
Ignore duplicates let’s you ignore duplicate values, which can be useful if you have sensors or topics that only update every few hours. Enabling ignore duplicates will cause the widget to only update when the value changes.
Number of values let’s you define how many values should be shown. Together with the update interval you can create widgets that (roughly) show data over 24 hours or any other amount of time.
Update interval sets the minimum amount of time in hours that has to pass for a widget to update. If it's set to 1, the widget will update at most once per hour. If it's set to 0 the widget will update whenever it's allowed. This can vary a bit since iOS decides when to update a widget, usually it's around every 15-30 minutes but if you for example have battery saving mode on this can slow down a bit.
Unit and Title are mostly just descriptions to make it look prettier, they don't have any function other than being displayed on the widget
Broker sets which broker to use for the widget/graph.
Graph color defines the color of the graph.