Die Konfiguration abrufen

Mit GET /device/config erfährt dein Gerät, welche Sensorcodes es melden soll und wie oft es misst. Mit dem ETag lädst du sie nur herunter, wenn sich etwas geändert hat.

Was sie enthält#

Für Regelkreis 201 (Kollektor, Speicher unten, Speicher oben, Pumpe), gekürzt auf zwei Sensoren:

{
  "config_version": "9f2c1a0b7d3e4f56",
  "device": {"id": 42, "name": "Attic", "mode": "live"},
  "intervals": {"scan_seconds": 60},
  "controller": {
    "brand": "OEG", "model": "KSW-E, KSW, KS2W", "protocol": "modbus_ascii",
    "connection": {"slave_address": 128, "baudrate": 9600, "parity": "E",
                   "bytesize": 7, "stopbits": 1, "timeout_ms": 1000}
  },
  "sensors": [
    {"sensor": "T1", "name": "Temperatuur zonnepaneel", "type": "collector_temp",
     "category": "temperature", "unit": "°C", "position": null,
     "address": {"register": 38, "decimals": 1, "signed": true, "function_code": 3},
     "plausible_min": -50.0, "plausible_max": 250.0},
    {"sensor": "R2", "name": "Pomp", "type": "pump",
     "category": "relay", "unit": null, "position": null,
     "address": {"register": 58, "decimals": 1, "signed": true, "function_code": 3},
     "plausible_min": null, "plausible_max": null}
  ]
}

Feld	Bedeutung
config_version	Ein Hash des Inhalts. Gleich dem ETag, ohne die Anführungszeichen
device	ID, Name und Modus (live oder simulated) des Geräts
intervals.scan_seconds	Wie oft das Gerät misst, in Sekunden. Standardmäßig 60. Im Portal als Abfrageintervall angezeigt, dort aber nicht änderbar
controller	Der Regler des Regelkreises: Marke, Modell, protocol (wie er ausgelesen wird) und connection (die Einstellungen dieses Protokolls). null, solange das Gerät keinen Regelkreis hat
sensors	Die Sensoren des Regelkreises

Pro Sensor:

Feld	Bedeutung
sensor	Der Code, den du mit jedem Messwert sendest, etwa T1 oder R2
name	Der Name, den das Portal anzeigt. Nur zur Anzeige; die Sensornamen im Katalog sind auf Niederländisch
type	Was der Sensor misst, unabhängig von der Marke: collector_temp, tank_bottom_temp, solar_pump, …
category	temperature, relay (ein Ausgang wie eine Pumpe oder ein Ventil), energy oder flow
unit	Einheit, etwa °C, kWh oder l/min. null bei Ausgängen
position	Welcher Speicher oder Kollektor, bei Anlagen mit mehr als einem. Sonst null
address	Wo der Regler den Wert ablegt, in der Form des Protokolls. null, wenn der Regler diesen Sensor nicht hat. Siehe unten
plausible_min, plausible_max	Der Bereich, in dem ein Wert stimmen kann. null bei Ausgängen

Abfragen mit ETag und 304#

Die Antwort hat einen ETag-Header:

ETag: "9f2c1a0b7d3e4f56"

Sende ihn beim nächsten Mal unverändert zurück:

If-None-Match: "9f2c1a0b7d3e4f56"

Nichts geändert: 304 Not Modified ohne Body. Etwas geändert: 200 mit der neuen Konfiguration und dem neuen ETag.

• Ein komprimierender Proxy macht aus dem ETag manchmal W/"…" oder "…-gzip". Sende zurück, was du bekommen hast: Der Server erkennt auch diese Formen.
• Alle 15 Minuten reicht; die BoilerBuddy Alpo macht es genauso. Jede Anfrage zählt zu deinen 60 pro Minute.
• Sie ändert sich, wenn der Eigentümer den Regelkreis oder den Gerätenamen ändert, oder wenn BoilerBuddy das Abfrageintervall oder den Sensorkatalog ändert.
• Speichere die letzte Konfiguration dauerhaft auf dem Gerät, damit das Gerät nach einem Neustart auch ohne Internet messen kann.

Ohne Regelkreis#

Direkt nach dem Anlegen oder Koppeln hat ein Gerät oft controller auf null und eine leere sensors-Liste. Sende dann noch nichts: Jeder Code würde in Quarantäne gehen. Frag weiter ab, bis der Eigentümer einen Regelkreis wählt; dann ändert sich der ETag.

Nur Codes aus der Konfiguration#

Sende nur Codes, die in sensors stehen; jeder andere Code geht in Quarantäne (siehe Messwerte senden). Kannst du einen Sensor kurz nicht lesen, sende "quality": "no_response" mit "value": null.

Den Regler auslesen#

controller.protocol sagt, wie der Regler ausgelesen wird. controller.connection und die address jedes Sensors haben die Form dieses Protokolls. Heute ist das immer Modbus; weitere Protokolle können folgen. Kennst du das Protokoll nicht, lies nichts aus und frag weiter ab.

Modbus#

Für modbus_ascii und modbus_rtu, wie bei der Alpo:

1. Öffne die serielle Schnittstelle mit den Einstellungen in connection: slave_address, baudrate, parity (E, O oder N), bytesize und stopbits. timeout_ms ist die Wartezeit pro Anfrage.
2. Lies für jeden Sensor ein 16-Bit-Register an address.register mit address.function_code (3 ist „Read Holding Registers“, 4 „Read Input Registers“). signed: true bedeutet Zweierkomplement. Überspringe Sensoren ohne address.
3. Teile durch 10 hoch decimals: Rohwert 614 mit decimals: 1 ist 61,4.
4. 32767, -32768, 65535 oder -9999 bedeutet „kein Sensor“: Sende sensor_fault ohne Wert.
5. Außerhalb von plausible_min und plausible_max: Sende den Wert mit out_of_range.
6. Keine Antwort: Sende no_response ohne Wert.

Bei den OEG-KSW-Reglern (KSW-E, KSW und KS2W) liegen T1 bis T6 in den Registern 38 bis 43, R1 in 57, R2 in 58 und R3 in 31, alle mit einer Nachkommastelle, vorzeichenbehaftet und mit Funktionscode 3.

Liest du deine Sensoren auf andere Weise aus, ignoriere controller und address und nutze nur sensor, type, category, unit und den plausiblen Bereich. Siehe Dein eigenes BoilerBuddy bauen.