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.
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
- Open the Aqua-Scope App
- Select the device
- Navigate to Configuration → Communication Options
- Enter the MQTT connection details
Configuration Parameters
| Parameter | Description |
|---|---|
server | Hostname or IP address of the MQTT broker |
port | Broker port (default: 1883, TLS: 8883) |
login | Username (optional) |
password | Password (optional) |
enable | Enable (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:
| Topic | Direction | Description |
|---|---|---|
/AQS/12345678/stat | Device → Broker | Regular status messages |
/AQS/12345678/alarm | Device → Broker | Alarm messages |
/AQS/12345678/cmnd | Broker → Device | Control 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
}
| Field | Description |
|---|---|
alarm | Alarm type (e.g., flood, overpressure, underpressure, temperature) |
state | 1 = alarm active, 0 = alarm cleared |
source | 0 = main device, 1 or higher = sub-device (e.g., paired flood sensor or motor) |
value | Current 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
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:
| Broker | Host | Port |
|---|---|---|
| HiveMQ Public | broker.hivemq.com | 1883 |
| EMQX Public | broker.emqx.io | 1883 |
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
- 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.
- Open io.aqua-scope.com/mqtt, pick the same broker, enter the 8-character device ID and click Connect.
- 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. - 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) orCmd+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.
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: