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.
Ü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.
- Mach den Selbsttest: 2 Register ab Protokolladresse 41000 müssen die Kennung
WWGWliefern. Schlägt der fehl, liegt es an der Umrechnung — nicht am Gerät. - Lass dir die Fehlerausgabe deines Clients gespeichert anzeigen. Bei SPS-Bausteinen stehen
ERRORundSTATUSoft nur einen einzigen Zyklus lang an und sind sonst nie zu sehen. - Steht die Verbindung überhaupt?
active_connectionsin/api/v1/modbus/statuszeigt, 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}}'
