Skip to main content

MQTT Integration

All Aqua-Scope WiFi devices support MQTT for integration into smart home systems, custom dashboards, or automation platforms such as Home Assistant, Node-RED, or ioBroker.

Home Assistant users

If you use Home Assistant, follow the step-by-step Home Assistant Integration guide — it sets up the MQTT broker, user and Discovery for you.

Enabling MQTT​

MQTT can be enabled in two ways:

During Initial Setup (Configuration Page)​

During the WiFi setup, you can enter the MQTT connection details directly under "Advanced".

Later via the App​

  1. Open the Aqua-Scope App
  2. Select the device
  3. Navigate to Configuration → Communication Options
  4. Enter the MQTT connection details

Configuration Parameters​

ParameterDescription
serverHostname or IP address of the MQTT broker
portBroker port (default: 1883, TLS: 8883)
loginUsername (optional)
passwordPassword (optional)
enableEnable (1) or disable (0) the service

Example JSON downlink for MQTT configuration:

{
"mqtt": {
"enable": "1",
"server": "my-broker.example.com",
"port": 1883,
"login": "username",
"password": "password"
}
}

MQTT over TLS​

Aqua-Scope devices support MQTT over TLS for encrypted connections. Use port 8883 (or the TLS port configured on your broker). The devices validate the server certificate automatically.

MQTT Topics​

All topics use the 8-character device ID (printed on the device). Example with device ID 12345678:

TopicDirectionDescription
/AQS/12345678/statDevice → BrokerRegular status messages
/AQS/12345678/alarmDevice → BrokerAlarm messages
/AQS/12345678/cmndBroker → DeviceControl commands to the device

Message Format​

All MQTT messages use JSON. The values follow the same format as the JSON Webhook service.

Status Message (stat)​

Example of a regular status message:

{
"uptime": 12345,
"temperature": 22.5,
"pressure": 3200,
"battery": 3.1
}

The included fields vary depending on the device type (e.g., rainlevel for the rain gauge, pressure for the pressure sensor).

Alarm Message (alarm)​

{
"alarm": "flood",
"state": 1,
"source": 0,
"value": 0
}
FieldDescription
alarmAlarm type (e.g., flood, overpressure, underpressure, temperature)
state1 = alarm active, 0 = alarm cleared
source0 = main device, 1 or higher = sub-device (e.g., paired flood sensor or motor)
valueCurrent sensor value that triggered the alarm (e.g., pressure in mBar for underpressure alarm, temperature for frost alarm). Not present for all alarm types.

Control Commands (cmnd)​

Example — close valve:

{"valve": "0"}

Example — open valve:

{"valve": "100"}

Test Tool: Watch MQTT Messages Live​

Online tester

io.aqua-scope.com/mqtt — free browser-based tool that connects to a public MQTT broker and displays every message of an Aqua-Scope device in real time. No install, no sign-up.

The tool is useful to

  • verify, before setting up your own broker, that the device is actually sending MQTT messages and to see what the real topics and JSON payloads look like,
  • when troubleshooting your own broker, test device and broker independently — if the tool shows messages, the fault is not in the device,
  • inspect the Home Assistant Discovery messages (topic homeassistant/.../config) that the device sends once when Home Assistant Support is activated,
  • document control commands and alarm payloads before switching to production.

Features​

After opening the page, pick one of two public, anonymously accessible MQTT brokers:

BrokerHostPort
HiveMQ Publicbroker.hivemq.com1883
EMQX Publicbroker.emqx.io1883

Additional controls:

  • Device ID — the 8-character ID of the device (printed on the device)
  • Topic prefix — defaults to AQS, adjust if your configuration uses a different prefix
  • "Device" channel — subscribes to AQS/<ID>/# (status, alarms, commands)
  • "Home Assistant Config" channel — subscribes to homeassistant/+/<ID>_*/config (discovery messages)

After clicking Connect, incoming messages appear chronologically in the log, each with a timestamp, the full topic and a formatted JSON payload. A counter shows the total number of received messages.

Steps​

  1. In the Aqua-Scope app, open Configuration → Communication Options, enter one of the two brokers as MQTT server (leave username and password empty), then save.
  2. Open io.aqua-scope.com/mqtt, pick the same broker, enter the 8-character device ID and click Connect.
  3. Within a few seconds, status messages (/AQS/<ID>/stat) and — if triggered — alarm messages (/AQS/<ID>/alarm) appear with the full topic and JSON payload.
  4. After the test, switch the MQTT server setting in the app back to your production broker.

If messages show up, the MQTT side of the device is working correctly and any remaining debugging can focus on your own broker. If nothing arrives at all, check Wi-Fi connectivity, device clock and firewall rules on the device.

Inspect and Download the Source Code​

The tool consists of a single, self-contained HTML file with embedded JavaScript — no build pipeline, no trackers, no analytics. The complete source code can therefore be reviewed directly in the browser:

  • In the browser: press Ctrl+U (Windows/Linux) or Cmd+Alt+U (macOS) to open the source view.
  • Download: right-click → "Save Page As…" stores the full file locally.
  • Command line: curl -O https://io.aqua-scope.com/mqtt

The locally saved file is fully functional — open it in any browser and it connects, unchanged, to the chosen public broker. This lets you verify exactly what data the tool sends, receives and displays.

Public brokers — testing only

broker.hivemq.com and broker.emqx.io are visible to anyone — in this mode, status values, alarms and valve commands are publicly readable. Use them only for testing, never in production.

Supported Devices​

MQTT is supported by all WiFi-enabled Aqua-Scope devices: