Documentation

Complete guide to setting up and using MQTT Dashboard Client

Table of Contents

  1. Broker Connection
  2. Widgets
  3. Widget Parameter Configuration
  4. Data Processing (JsonPath, Regex)
  5. Prefix and Suffix
  1. Widget Groups
  2. Scripts and Automation
  3. Scenes
  4. SSL/TLS Certificates
  5. Backup and Restore

1. Broker Connection

An MQTT broker is a server through which devices exchange messages. To get started, add at least one broker.

How to Add a Broker
  1. 1 Open the Brokers tab (bottom menu)
  2. 2 Tap the + button in the bottom right corner
  3. 3 Fill in the required fields:
    • Name — any name (e.g., "Home Server")
    • URL — broker IP address or domain
    • Port — port (1883 for TCP, 8883 for SSL)
    • Protocol — select tcp://, ssl://, ws:// or wss://
  4. 4 Optionally enable Authentication and enter username/password
  5. 5 Configure additional parameters (Client ID, Clean Session, Keep Alive Interval, Auto Connect)
  6. 6 Tap Done
Tip: Enable Auto Connect so the broker connects automatically when the app starts.

2. Widgets

Widgets are the main UI elements for displaying data from the broker and sending commands.

Creating a Widget
  1. 1 On the main screen, tap an empty cell or the + button
  2. 2 Enter the Widget Name and select a Group to add it to
  3. 3 Choose the number of parameters (1 to 4) using the horizontal pager — each parameter can have its own type, topic and settings
  4. 4 Tap a parameter in the list to configure its type, topics and data processing — see the Widget Parameter Configuration section for details
  5. 5 Tap Done to complete creation
A single widget can contain up to 4 parameters of different types (e.g., text + button + switch).
Widget Management
  • Drag and Drop: long-press a widget and drag it to a new location. Empty cells are highlighted.
  • Context Menu: long-press a widget to open the menu (edit, delete, move to group)
  • Editing: tap a widget to open detailed info and settings

3. Widget Parameter Configuration

Each parameter added during widget creation can be configured individually: choose the type, topics, and data processing. Click a parameter type below to expand its detailed configuration guide.

The Text widget displays arbitrary text data from an MQTT topic: statuses, messages, sensor readings.

Configuration:

  1. Subscription Topic — the topic to receive data from
  2. JsonPath / Regex — if the data is in JSON, configure extraction of the field
  3. Prefix / Suffix — add text before or after the value
Example: Sensor publishes {"status": "Door open"}. JsonPath: $.status → displays "Door open".

The Boolean widget displays and controls binary device states (on/off, open/closed).

Basic settings:

  1. Subscription Topic — receive device state
  2. Send Topic — send on/off commands
  3. Values — specify what message is "On" (e.g. 1) and "Off" (e.g. 0)
  4. JsonPath / Regex — extract state from JSON payload

Confirmation mode:

Without confirmation: The app sends a command and switches the widget immediately. If the incoming message matches "On" — widget is on, otherwise off.
Example: "On" = 1. Receiving 1 → on, 0 or any other value → off.
With confirmation: Separate topics are used for sending commands and receiving state. The app waits for a response from the device.
Setup: Send topic home/light/set, subscription topic home/light/status.
Flow: Tap → command to .../set → device confirms in .../status → widget updates.
Troubleshooting: If the switch turns off immediately after turning on — check incoming messages in the Terminal. The topic may publish unexpected values. Also ensure the send and subscription topics are different.

The Switch widget is visually similar to Boolean but rendered as a button. Settings are identical.

  1. Subscription Topic — receive device state
  2. Send Topic — send commands
  3. Values — configure "On" and "Off" values
  4. JsonPath / Regex — extract state from payload

For confirmation mode details, see the Boolean section above.

The Button widget sends a predefined message to a topic on each tap.

Configuration:

  1. Send Topic — the target topic
  2. Value — the fixed message to send (e.g. RESET or {"command": "reboot"})
  3. QoS — quality of service (0, 1, 2)
  4. Prefix / Suffix — for building complex messages
Example: "Reboot router" button. Topic: home/router/command, value: reboot.

The Numeric widget displays numeric sensor readings: temperature, humidity, voltage, etc.

Configuration:

  1. Subscription Topic — receive numeric data
  2. Decimal Places — number of displayed decimal digits
  3. JsonPath / Regex — extract number from payload
  4. Prefix / Suffix — for units of measurement (e.g. °C)
Example: Sensor publishes {"temperature": 25.5}. JsonPath: $.temperature, decimal places: 1, suffix: °C → "25.5°C".

The Regulator widget sends numeric values using a slider. Suitable for dimmers, volume, brightness.

Configuration:

  1. Send Topic — send the slider value
  2. Subscription Topic — receive current value (optional, for synchronization)
  3. Min / Max / Step — range and step size (e.g. 0–100, step 1)
  4. Prefix / Suffix — for formatting outgoing data
Example: Dimmer with range 0–255. Send topic: home/light/dimmer/set, subscription topic: home/light/dimmer/status.

The Color widget lets you pick and send colors for RGB strips and bulbs.

Configuration:

  1. Send Topic — send the selected color
  2. Subscription Topic — receive current device color
  3. Format — HEX (#FF0000), RGB (255,0,0) or XY (for Philips Hue)
  4. JsonPath — extract color from JSON

The URL Image widget loads and displays an image from a URL received via MQTT.

Configuration:

  1. Subscription Topic — receive the image URL
  2. JsonPath — extract the URL from a JSON message
Example: Camera publishes {"image": "http://cam.local/snapshot.jpg"}. JsonPath: $.image.

The Location widget displays coordinates on a map. This feature is in development.

  1. Subscription Topic — receive coordinates
  2. JsonPath — extract coordinates from JSON

4. Data Processing

The app supports multiple ways to extract data from MQTT payloads.

JsonPath FREE

Extracts a value from a JSON message.

Example:
Payload: {"temperature": 25.5, "humidity": 60}
JsonPath: $.temperature → 25.5

Supports dot notation ($.object.array[0].value) and bracket notation ($[\'store\'][\'book\'][0][\'title\']).

Regex PREMIUM

Extracts data using regular expressions. Works as a second stage after JsonPath.

Three-step pipeline:

  1. JsonPath → extract field from JSON
  2. Regex (primary) → extract data from string
  3. Regex (secondary) → post-process the result
Example:
Payload: {"data": "temp: 25.5C hum: 60%"}
1. JsonPath $.data → "temp: 25.5C hum: 60%"
2. Regex temp:\s*([\d.]+)C → 25.5

Regex Time — separate expression for extracting a timestamp from the payload.

JsonPath for Time FREE

Extracts a timestamp from a separate JSON field.

  • Specify a JsonPath to the time field
  • Time zone correction — slider from -12 to +12
  • Supports various date/time formats

5. Prefix and Suffix

Add text before and after values for formatting.

Outgoing Data FREE

Format data before sending to the broker.

Example: slider = 1
Prefix: {"command": "
Suffix: "}
Result: {"command": "1"}

Useful for building JSON commands.

Incoming Data PREMIUM

Format received data before displaying on the widget.

Example: sensor = 42
Suffix: °C
Result: 42°C

Convenient for adding measurement units.

6. Widget Groups

Groups help organize widgets by meaning — for example, "Sensors", "Light Control", "Temperature".

  1. 1 Open the Groups tab (bottom menu) or create a group from the main screen
  2. 2 Tap Create Group
  3. 3 Give the group a name and select an icon
  4. 4 Drag widgets on the main screen directly into a group via the context menu

On the main screen, groups are displayed as tabs or a list — you can switch between them and see only the relevant widgets.

7. Scripts and Automation PREMIUM

Scripts allow you to automate actions: send messages based on conditions, execute scenarios on app start, and more.

Creating a Script
  1. 1 Menu → Scripts
  2. 2 Tap + to create a new script
  3. 3 Configure conditions:
    • By topic — when a message is received on a specific topic
    • By value — when a value matches (greater than, less than, equal)
    • By timer — scheduled
    • App Start Condition — executes when the application starts
  4. 4 Combine conditions using a Logical Block (AND / OR) for complex logic
  5. 5 Configure actions:
    • Send a message to a topic
    • Notification / sound alert
    • Delay before the next action
  6. 6 Enable the script — toggle switch on the script card. Disabled scripts won't execute but remain editable
Example: "If temperature > 30°C AND humidity < 20% → send command to turn on humidifier and show notification"

A disabled script can be opened and edited — changes are saved and take effect when the script is re-enabled.

8. Scenes

Scenes let you send multiple commands to different devices with a single tap.

  1. 1 In the menu, select Scenes
  2. 2 Create a new scene and add commands (broker + topic + message)
  3. 3 Run the scene — all commands will be sent simultaneously
Example: "Leave Home" scene — turn off lights, close blinds, turn off air conditioner.

9. SSL/TLS Certificates PREMIUM

Connect to brokers with encryption and custom certificates.

Self-signed Certificate
  1. When creating a broker, select ssl:// or wss:// protocol
  2. Enable Self-signed Certificate
  3. The app will trust any certificate from this broker

Suitable for local servers (Raspberry Pi, home server).

Custom CA Certificate
  1. Select ssl:// or wss:// protocol
  2. The Self-signed option must be disabled
  3. Tap Select certificate file
  4. Select a .pem file via file manager

For corporate and cloud MQTT brokers.

10. Backup and Restore

Save and restore your complete app configuration — all widgets, brokers, scripts, scenes, and settings.

Create a Backup
  1. 1 Settings → Configuration Backup
  2. 2 Optionally enable data logs (sensor value history)
  3. 3 Tap Create and choose a save location
What Gets Saved

Widgets

  • Type, icon, color, style
  • Label and displayed data
  • Position and size on the main screen (separate for portrait and landscape)
  • Subscription topics, JsonPath, Regex, prefix/suffix
  • Outgoing data settings (topic, QoS, format)

Brokers

  • Connection address and port
  • Username and password
  • SSL/TLS settings and certificates

Widget Groups

  • Name, icon, and group order

Scripts and Automation

  • All scripts with names and state (enabled/disabled)
  • Conditions — by topic, value, timer, on app start
  • Logical blocks (AND / OR)
  • Actions — send message, notification, sound, blink, delay

Scenes

  • Scenes with command sets (broker + topic + message)

App Settings

  • All general preferences, favorite colors, widget order
  • Pending messages
  • Sensor data history (optional)
Restore
  1. 1 Settings → Configuration Recovery
  2. 2 Select the backup file
  3. 3 After restoration the app will restart. Client IDs will change to avoid connection conflicts
Restoring replaces all current app data. We recommend creating a fresh backup before restoring.