Zum Inhalt

Modbus TCP

Der WattWächter Gas stellt einen integrierten Modbus TCP Server bereit. Zählerstand, Durchfluss und Energie sind damit direkt als Modbus-Register abrufbar — geeignet für Home Assistant, openHAB, ioBroker, Loxone, SCADA-Systeme und jeden anderen Modbus-TCP-Client.

Eigener Registerblock, kein SunSpec

Ein Gaszähler hat mit einem Drehstromzähler nichts gemeinsam, deshalb spricht der WattWächter Gas kein SunSpec. Er liefert einen eigenen Registerblock ab Adresse 41000 — siehe Registerblock.

Voraussetzungen

  • WattWächter Gas eingerichtet und mit dem WLAN verbunden — falls noch nicht geschehen, folge zunächst der Einrichtung
  • Modbus-TCP-Client im selben Netzwerk

  • Port 502 (Standard) erreichbar zwischen Client und WattWächter


Modbus TCP aktivieren

Die Modbus-Schnittstelle ist ab Werk deaktiviert und muss einmalig eingeschaltet werden. Du hast drei Möglichkeiten:

Über die Weboberfläche (empfohlen) — ruf den WattWächter im Browser auf, entweder über seinen mDNS-Namen http://wattwaechter-XXXXXXXXXXXX.local oder über seine IP-Adresse, und klicke auf Einstellungen. Wähle dort den Abschnitt Modbus TCP (Gruppe Integrationen), schalte Modbus-TCP-Server aktivieren ein und bestätige unten mit Speichern.

Das Feld Port steht auf 502 und muss nur angefasst werden, wenn dieser Port bei dir schon belegt ist.

Weboberfläche: Modbus TCP in den Einstellungen aktivieren

Über den API-Explorer — öffne die Web-UI des WattWächters, klicke auf „API-Explorer", wähle den Endpunkt POST /api/v1/settings und sende folgenden Body:

{ "modbus": { "enable": true, "port": 502 } }

Per curl — falls du es lieber von der Kommandozeile erledigst:

curl -X POST http://wattwaechter-XXXXXXXXXXXX.local/api/v1/settings \
  -H "Authorization: Bearer WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modbus": {
      "enable": true,
      "port": 502
    }
  }'

Die Änderung wird sofort übernommen — ein Neustart ist nicht erforderlich. Du kannst den Port anpassen, falls 502 bereits belegt ist.

API-Authentifizierung deaktiviert?

Ist die API-Authentifizierung ausgeschaltet (Werkseinstellung), kannst du den Authorization-Header weglassen. Siehe REST-API.


Verbindungsdaten

Parameter Wert
Protokoll Modbus TCP
Port 502 (konfigurierbar)
Unterstützte Function Codes 0x03 (Read Holding Registers), 0x04 (Read Input Registers)
Max. gleichzeitige Clients 2
Idle-Timeout 5 Minuten
Byte-Order Big-Endian (Modbus-Standard)
Register-Basis 41000 (eigener Registerblock)

Als Host wird der mDNS-Name (wattwaechter-XXXXXXXXXXXX.local) oder die IP-Adresse des Geräts verwendet. Wie du die IP-Adresse findest, ist in den FAQs beschrieben.

Loxone: nur die IP-Adresse

Nicht jeder Client löst mDNS auf. Loxone kann mit .local-Namen nichts anfangen — dort muss die IP-Adresse stehen, abgesichert über eine DHCP-Reservierung oder eine feste IP. Details unter Integrationen → Loxone.


Adresskonvention

Alle Adressen auf dieser Seite sind Protokolladressen — also genau die Zahl, die im Modbus-Telegramm steht. 41010 ist die Zahl auf dem Draht, keine Modicon-Referenz im Sinne des klassischen „4xxxx"-Schemas.

Das ist wichtig, weil Clients diese Zahl unterschiedlich entgegennehmen:

Client Eingabe für Protokolladresse 41010 Regel
pymodbus, Home Assistant, openHAB, Node-RED, Loxone, ioBroker 41010 unverändert
modpoll in der Voreinstellung und andere Werkzeuge, die ab 1 zählen 41011 +1 — oder das Werkzeug auf 0-basierte Zählung umstellen (bei modpoll: -0)
Siemens S7 MB_CLIENT (Parameter MB_DATA_ADDR) 441011 +400001

Der Sonderfall bei der S7: MB_DATA_ADDR erwartet eine Modicon-Referenz und zieht davon 40001 ab — im Bereich 40001–49999, der aber nur bis zur Protokolladresse 9998 reicht. Für unsere Adressen ist deshalb der erweiterte Bereich ab 400001 nötig, von dem der Baustein 400001 abzieht. Details unter Integrationen → Siemens S7.

Gibt dein Client eine Modbus-Ausnahme 02 (illegal data address) zurück oder liefert er nur Nullen, ist fast immer diese Umrechnung die Ursache — siehe Fehlerbehebung.

Selbsttest in einem Zug

Lies 2 Register ab Protokolladresse 41000. Kommt die Kennung WWGW zurück, stimmt deine Adressierung — dann kannst du alle weiteren Adressen dieser Seite nach derselben Regel umrechnen.


Registerblock

Der WattWächter Gas liefert einen eigenen Registerblock an den Protokolladressen 41000–41031; alle anderen Adressen beantwortet er mit der Modbus-Ausnahme 02 (illegal data address). Aktivieren, Port und Verbindungsdaten sind wie oben beschrieben.

Gas und Wasser nutzen dieselben Adressen — stellst du das Medium um, bleiben die Adressen gleich. Welches Medium anliegt, steht in Med.

Adresse Feld Typ Einheit Bedeutung
41000 Magic char[4] — Kennung WWGW
41002 Ver uint16 — Layout-Version, aktuell 1
41003 L uint16 — Länge des Datenteils in Registern, aktuell 22
41004 Ser uint8[6] — Seriennummer (MAC-Adresse)
41007 Fw uint32 — Firmware-Version (Major, Minor und Patch in je einem Byte, Major oben)
41010 Vol float32 m³ Zählerstand
41012 VolFlw float32 m³/h Durchfluss
41014 Ene float32 kWh Energiezähler (nur Gas, bei Wasser NaN)
41016 EneF float32 kWh/m³ Umrechnungsfaktor Zustandszahl × Brennwert (nur Gas, bei Wasser NaN)
41018 PlsVol float32 m³ Volumen je Impuls
41020 Pwr float32 kW Leistung = Durchfluss × EneF (nur Gas, bei Wasser NaN)
41022 Pls uint32 — Impulse seit der Zählerstandseingabe
41024 Med uint16 — Medium: 0 = Gas, 1 = Wasser
41025 Src uint16 — Sensor: 1 = Magnetfeld, 2 = induktiv
41026 St uint16 — Status (Bitfeld): Bit 0 = Sensor antwortet, Bit 1 = Durchfluss auf 0 gesetzt, Bit 2 = seit dem Start noch kein Impuls
41027 StpRev uint16 — Impulse je Umdrehung (6)
41028 MedStr char[8] — Medium als Text (gas / water)

Alle Messwerte sind float32, Big-Endian mit dem höherwertigen Register zuerst — Skalierungsfaktoren gibt es nicht. Nicht belegte Werte tragen NaN. Die Weboberfläche zeigt die Register mit ihren aktuellen Werten unter Einstellungen → Modbus TCP, sobald der Server läuft.

Ene ist ein echter Energiezähler: Jeder m³ zählt mit dem Umrechnungsfaktor, der beim Verbrauch galt. Trägst du mit einem neuen Tarif einen anderen Brennwert ein, wirkt er nur auf künftigen Verbrauch, und eine Zählerstandskorrektur ändert Ene nicht. Du kannst Ene deshalb direkt als Verbrauchszähler auslesen. Den Zählerstand in kWh nach heutigem Faktor bekommst du aus Vol × EneF.

Status-Endpunkt

Der REST-Endpunkt /api/v1/modbus/status zeigt, ob der Server läuft, wie viele Clients verbunden sind und welche Werte gerade in den Registern stehen — praktisch, um einen Modbus-Client einzurichten oder eine falsche Adresse zu finden:

curl http://wattwaechter-XXXXXXXXXXXX.local/api/v1/modbus/status \
  -H "Authorization: Bearer READ_TOKEN"

Antwort (gekürzt):

{
  "enabled": true,
  "running": true,
  "port": 502,
  "active_connections": 1,
  "registers": [
    {
      "register": 41010,
      "name": "Vol",
      "obis": "7-0:3.0.0",
      "value": 1234.5670,
      "unit": "m³",
      "valid": true,
      "raw": 1150964261,
      "scale_factor": 0,
      "scale_register": 0,
      "derived": false
    },
    {
      "register": 41012,
      "name": "VolFlw",
      "obis": "7-0:43.0.0",
      "value": 0.3500,
      "unit": "m³/h",
      "valid": true,
      "raw": 1051931443,
      "scale_factor": 0,
      "scale_register": 0,
      "derived": false
    },
    {
      "register": 41024,
      "name": "Med",
      "obis": "",
      "value": 0.0000,
      "unit": "",
      "valid": true,
      "raw": 0,
      "scale_factor": 0,
      "scale_register": 0,
      "derived": true
    }
  ]
}

Die Felder bedeuten dasselbe wie beim WattWächter Plus, mit drei Unterschieden: scale_factor und scale_register sind immer 0, weil der Registerblock keine Skalierung kennt. raw ist bei float32-Werten das Bitmuster der beiden Register als vorzeichenlose Zahl. derived ist true bei allen Feldern, die das Gerät aus Einstellungen und Zählerzustand bildet — nur Vol und VolFlw haben eine OBIS-Kennzahl. Ist der Server aus, bleibt registers leer.

Fehlerbehebung

Verbindung wird abgelehnt / Timeout
  • Ist Modbus in den Einstellungen aktiviert? Prüfe /api/v1/modbus/status → enabled: true, running: true.
  • Verwendest du den richtigen Port? Standard ist 502.
  • Ist der Client im selben Netzwerk/Subnetz? In Gast-WLANs ist Client-zu-Client-Kommunikation meist gesperrt.
  • Es sind maximal 2 gleichzeitige Verbindungen möglich. Weitere Clients werden abgewiesen, bis eine Verbindung geschlossen wird oder nach 5 min Leerlauf.
Register liefern nur Nullen

Fast immer eine Frage der Adresskonvention. Der WattWächter beantwortet Adressen außerhalb seines Registerblocks mit der Modbus-Ausnahme 02 (illegal data address) — das ist Absicht, damit eine falsche Adresse auffällt, statt plausible Zahlen zu liefern. Viele Clients zeigen diese Ausnahme jedoch nur kurz oder gar nicht an und lassen ihren Datenbereich einfach auf 0 stehen.

  1. Mach den Selbsttest: 2 Register ab Protokolladresse 41000 müssen die Kennung WWGW liefern. Schlägt der fehl, liegt es an der Umrechnung — nicht am Gerät.
  2. Lass dir die Fehlerausgabe deines Clients gespeichert anzeigen. Bei SPS-Bausteinen stehen ERROR und STATUS oft nur einen einzigen Zyklus lang an und sind sonst nie zu sehen.
  3. Steht die Verbindung überhaupt? active_connections in /api/v1/modbus/status zeigt, ob dein Client durchgekommen ist.
Port 502 bereits belegt

Hast du bereits ein Gerät auf Port 502? Stelle in den Einstellungen einen alternativen Port ein, z.B. 1502:

curl -X POST http://wattwaechter-XXXXXXXXXXXX.local/api/v1/settings \
  -H "Authorization: Bearer WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modbus": {"port": 1502}}'