# MQTT (/docs/settings/mqtt)



<Callout title="Tip" type="info">
  New to MQTT? see the resources below:

  * [EMQX — Getting Started with MQTT](https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-mqtt)
  * [HiveMQ — MQTT Essentials](https://www.hivemq.com/mqtt/)
  * [AWS — What Is MQTT?](https://aws.amazon.com/what-is/mqtt/)

  To understand MQTT's publish and subscribe architecture, refer to

  * [EMQX — MQTT 5: Introduction to the Publish/Subscribe Model](https://www.emqx.com/en/blog/mqtt-5-introduction-to-publish-subscribe-model)
  * [HiveMQ — MQTT Essentials Part 2: Publish & Subscribe](https://www.hivemq.com/blog/mqtt-essentials-part2-publish-subscribe)
</Callout>

## 1. Introduction [#1-introduction]

Message Queueing Telemetry Transport ([MQTT](https://mqtt.org)) is a
lightweight messaging protocol for devices with limited resources. MQTT is
built on top of TCP/IP and is ideal for machine-to-machine communication and
the Internet of Things (IoT).

Webview Kiosk utilises the MQTT protocol to enable you to remotely:

* receive events
* update app settings
* perform actions via commands
* request information

## 2. MQTT Broker [#2-mqtt-broker]

To communicate with Webview Kiosk, you will need an
[MQTT Broker](https://www.emqx.com/en/blog/the-ultimate-guide-to-mqtt-broker-comparison).
The broker acts as an intermediary entity (central hub) that routes messages
between devices and applications.

Our recommendation for open source, self-hostable brokers (server) and clients
(to send messages to Webview Kiosk) are:

1. [EMQX](https://github.com/emqx/emqx) and [MQTTX](https://github.com/emqx/MQTTX) (or [MQTTX Web](https://github.com/emqx/MQTTX/tree/main/web))
2. [Eclipse Mosquitto](https://github.com/eclipse-mosquitto/mosquitto) and
   [Home Assistant](https://github.com/home-assistant) - see the
   [Integration Guide](https://www.home-assistant.io/integrations/mqtt)

   <Callout title="Tip" type="info">
     Here is a third-party integration with Home Assistant:

     * [https://github.com/RcRaCk2k/ha\_webview\_kiosk](https://github.com/RcRaCk2k/ha_webview_kiosk)

     This project is community-built and not maintained by Webview Kiosk.
   </Callout>

There are also public brokers you can use for testing purposes, such as

* HiveMQ: [https://www.mqtt-dashboard.com](https://www.mqtt-dashboard.com)
* Mosquitto: [https://test.mosquitto.org](https://test.mosquitto.org)
* EMQX: [https://www.emqx.com/en/mqtt/public-mqtt5-broker](https://www.emqx.com/en/mqtt/public-mqtt5-broker)

## 3. Global Variables [#3-global-variables]

The following variables will be string-interpolated for supported settings,
such as topic names and will payload:

| Variable Name     | Description                             |
| ----------------- | --------------------------------------- |
| APP\_INSTANCE\_ID | Unique identifier for the app instance. |
| USERNAME          | MQTT username used for authentication.  |

To use variables in your settings, use the syntax `${YOUR_VARIABLE}`, e.g.

```js
wk/${USERNAME}/${APP_INSTANCE_ID}/command
```

which may evaluate to a string such as

```txt
// [!code word:kiosk_user_01]
// [!code word:b8378168-ca69-11f0-af20-5a93ec0e6f90]
wk/kiosk_user_01/b8378168-ca69-11f0-af20-5a93ec0e6f90/command
```

Some settings will support additional variables.

## 4. Debug Logs [#4-debug-logs]

MQTT operations are recorded in the debug logs, which can be accessed from any
MQTT settings screens. This includes:

* connecting/connected/disconnect
* subscribes
* messages received or published
* errors

A maximum of 100 messages will be stored for the duration of the app activity
lifecycle. The logs will not persist between app restarts.

## 5. Settings [#5-settings]

### 5.1. Enabled [#51-enabled]

Set to `true` to allow connections to your configured broker in `MQTT -> Connections`.

If you are currently in a disconnected state, you will need to manually click
the `Connect` button after enabling this option (or simply restart the app).

Updated MQTT settings do not get applied immediately if you are already
connected. Instead, you will need to reconnect by:

* clicking the restart button in MQTT settings
* manually restarting the application
* send a `Reconnect` command

**Default:** false

### 5.2. Use Foreground Service [#52-use-foreground-service]

Start a
[Foreground Service](https://developer.android.com/develop/background-work/services/fgs)
to keep the MQTT connection alive.

This will maintain the connection even when Webview Kiosk goes to the background
(e.g. another app is opened) or the device screen is turned off (by using
[PowerManager.PARTIAL\_WAKE\_LOCK](https://developer.android.com/reference/android/os/PowerManager.html#PARTIAL_WAKE_LOCK)).

Turn on notifications to see the current MQTT status being updated by the
foreground service every second.

Also, it is highly recommended that you disable battery optimisation for
Webview Kiosk to stop the service from being killed.

For more information, visit:

* [https://dontkillmyapp.com](https://dontkillmyapp.com)

**Default:** false