MQTT

The WattWächter Plus can publish its meter values as MQTT telemetry to any MQTT broker — suitable for Home Assistant, ioBroker, openHAB, Node-RED and any other system with an MQTT client.

Home Assistant Auto-Discovery

Sensors are announced automatically via Home Assistant MQTT discovery and appear as device entities without any manual YAML configuration. See Home Assistant Auto-Discovery below.

Prerequisites

• WattWächter Plus set up and connected to WiFi — if not yet done, see Getting Started first
• A reachable MQTT broker (e.g. Mosquitto, EMQX, HiveMQ, the Home Assistant add-on broker)
• For TLS: a matching CA certificate — see TLS connection below

---

Enable MQTT

MQTT is disabled by default. You can enable and configure it through all four configuration paths — web interface, smartphone app, Cloud Portal or REST API (see Settings for the general introduction). The minimum required values are:

• Enabled → true
• Broker hostname → DNS name or IP of the broker
• Port → 1883 (unencrypted) or 8883 (TLS, default)

Optional, depending on broker setup:

• Username / password (stored encrypted on the device)
• Custom client ID (default: the device ID wattwaechter-XXXXXXXXXXXX)
• Custom topic prefix (see Topic structure)
• Adjust publish interval (see Publish interval)
• Disable TLS if the broker is only reachable unencrypted
• CA certificate for self-signed brokers (see TLS connection)

Changes are applied without rebooting — the WattWächter reconnects immediately.

---

Topic Structure

All topics live under a configurable topic prefix. The default is:

WattWaechter/{client_id}

{client_id} defaults to the device ID (wattwaechter-XXXXXXXXXXXX, the last 12 characters of the MAC). Both the prefix and the client ID can be overridden in settings.

Topic	Content	Retained
{prefix}/status	online after a successful connection	yes
{prefix}/{obis}	Current meter value (see payload format)	yes
homeassistant/sensor/{client_id}_{obis_}/config	Home Assistant discovery definition	yes

Example topics for a device with ID wattwaechter-aabbcc112233:

WattWaechter/wattwaechter-aabbcc112233/status                        → online
WattWaechter/wattwaechter-aabbcc112233/1.8.0                         → 12345.678
WattWaechter/wattwaechter-aabbcc112233/2.8.0                         →    42.123
WattWaechter/wattwaechter-aabbcc112233/16.7.0                        →   -812.4
homeassistant/sensor/wattwaechter-aabbcc112233_1_8_0/config          → {JSON}

OBIS format in topics

The value topic uses the OBIS short form with dots (e.g. 1.8.0). The discovery topic replaces dots with underscores (1_8_0) because dots are not allowed in Home Assistant discovery topics.

---

Payload Format

Published meter values are raw float values as ASCII strings, without any JSON wrapper. Example: 12345.678. The number of decimal places depends on the value type (3 or 4 digits).

A list of all published OBIS codes is in the Device overview. Which values are actually published depends on the meter and the enabled OBIS codes.

---

Publish Interval

Controls the time between two telemetry publishes — i.e. how often the current meter values are sent to the broker.

Value
Default	60 s
Minimum	1 s
Unit	seconds

Very short intervals produce proportionally more network and broker load and are rarely needed for energy monitoring. For consumption statistics, 5–10 minutes is often enough. For live displays (e.g. "How much is the oven drawing right now?") 1–5 seconds makes sense.

---

Home Assistant Auto-Discovery

As soon as MQTT is active and the WattWächter has connected to the broker, Home Assistant discovery messages are published automatically for each known OBIS value. Home Assistant recognises the device as a WattWächter Plus without any manual YAML and creates a sensor per value.

Example discovery payload (for 1.8.0 – total energy in):

{
  "name": "Active Energy (A+R+)",
  "state_topic": "WattWaechter/wattwaechter-aabbcc112233/1.8.0",
  "device_class": "energy",
  "unit_of_measurement": "kWh",
  "state_class": "total_increasing",
  "unique_id": "wattwaechter-aabbcc112233_1_8_0",
  "device": {
    "identifiers": ["wattwaechter-aabbcc112233"],
    "name": "Wattwächter",
    "manufacturer": "SmartCircuits GmbH",
    "model": "WattWächter Plus"
  }
}

Discovery topics are retained — Home Assistant rediscovers the device immediately after a restart. They are published about 2 seconds after a successful connection and are not removed automatically when MQTT is later disabled. If you want the device to disappear from Home Assistant, delete the discovery topics manually (e.g. mosquitto_pub -r -n -t homeassistant/sensor/.../config).

Conflict with native HA integration

If the native Home Assistant integration is running in parallel, it detects the active MQTT discovery and warns. Use only one of the two sources, otherwise you will get duplicate entities.

---

TLS Connection

The default port is 8883 with TLS. The WattWächter verifies the broker certificate against a built-in CA bundle. For custom or self-signed certificates you can upload an additional CA certificate — see the POST /api/v1/mqtt/ca endpoint in the REST API reference.

For purely local brokers TLS can also be turned off entirely — the WattWächter then uses port 1883 unencrypted.

---

Authentication

Optional via username + password. Both fields are AES-encrypted before being written to device storage and are only decrypted at runtime — they cannot be read back in plaintext via the REST API.

Leave both fields empty if your broker allows anonymous connections.

---

Reconnect Behavior

If the connection drops, the WattWächter reconnects on its own. The wait time doubles after each failed attempt with ±25 % jitter:

1 s → 2 s → 4 s → 8 s → … → 256 s (cap)

After long outages (8 / 20 / 50+ consecutive failures) the cap is raised progressively up to 5 minutes to spare the broker.

Any change to the MQTT settings triggers an immediate reconnect with the new values.

---

Status & Diagnostics

The current connection state is exposed via GET /api/v1/mqtt/status (READ token):

{
  "enabled": true,
  "state": "CONNECTED",
  "host": "mqtt.example.com",
  "port": 8883,
  "client_id": "wattwaechter-aabbcc112233",
  "use_tls": true,
  "last_error": 0,
  "last_error_message": "",
  "reconnect_attempts": 0
}

Possible state values: OFF, INIT, CONNECTING, CONNECTED, WAIT_RETRY, FAILED.

---

Example: Subscribe with mosquitto_sub

# Stream all values of a device
mosquitto_sub -h mqtt.example.com -p 8883 \
  -t "WattWaechter/wattwaechter-aabbcc112233/#" -v

# Just the current power
mosquitto_sub -h mqtt.example.com -p 8883 \
  -t "WattWaechter/wattwaechter-aabbcc112233/16.7.0"