Configuratie ophalen

Met GET /device/config weet je apparaat welke sensorcodes het instuurt en hoe vaak het meet. Met de ETag haal je hem alleen op als er iets veranderd is.

Wat erin staat#

Voor regelkring 201 (collector, onderzijde en bovenzijde vat, pomp), ingekort tot twee sensoren:

{
  "config_version": "9f2c1a0b7d3e4f56",
  "device": {"id": 42, "name": "Zolder", "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}
  ]
}

Veld	Betekenis
config_version	Een hash van de inhoud. Gelijk aan de ETag, zonder aanhalingstekens
device	Id, naam en modus (live of simulated) van het apparaat
intervals.scan_seconds	Hoe vaak het apparaat meet, in seconden. Standaard 60. In het portaal te zien als Scaninterval, maar niet te wijzigen
controller	De regelaar van de regelkring: merk, model, protocol (hoe je hem uitleest) en connection (de instellingen van dat protocol). null zolang het apparaat geen regelkring heeft
sensors	De sensoren van de regelkring

Per sensor:

Veld	Betekenis
sensor	De code die je bij elke meting meestuurt, zoals T1 of R2
name	De naam in het portaal. Alleen voor weergave
type	Wat de sensor meet, los van het merk: collector_temp, tank_bottom_temp, solar_pump, …
category	temperature, relay (een uitgang zoals een pomp of klep), energy of flow
unit	Eenheid, zoals °C, kWh of l/min. null voor uitgangen
position	Welk vat of paneel, bij installaties met meer dan één. Anders null
address	Waar de regelaar de waarde bewaart, in de vorm van het protocol. null als de regelaar deze sensor niet heeft. Zie hieronder
plausible_min, plausible_max	Het bereik waarbinnen een waarde kan kloppen. null voor uitgangen

Pollen met ETag en 304#

Het antwoord heeft een ETag-header:

ETag: "9f2c1a0b7d3e4f56"

Stuur die de volgende keer ongewijzigd terug:

If-None-Match: "9f2c1a0b7d3e4f56"

Niets veranderd: 304 Not Modified zonder body. Wel veranderd: 200 met de nieuwe configuratie en ETag.

• Een proxy die comprimeert, maakt van de ETag soms W/"…" of "…-gzip". Stuur terug wat je kreeg: de server herkent die vormen ook.
• Elke 15 minuten is genoeg; de BoilerBuddy Alpo doet het ook zo. Elk verzoek telt mee in je 60 per minuut.
• Hij verandert als de eigenaar de regelkring of de naam wijzigt, of als BoilerBuddy het scaninterval of de sensorcatalogus aanpast.
• Bewaar de laatste configuratie op schijf, zodat het apparaat na een herstart ook zonder internet kan meten.

Zonder regelkring#

Net na het aanmaken of koppelen is controller vaak null en sensors leeg. Stuur dan nog niets: elke code gaat in quarantaine. Blijf pollen tot de eigenaar een regelkring kiest; dan verandert de ETag.

Alleen codes uit de configuratie#

Stuur alleen codes uit sensors; andere gaan in quarantaine (zie Metingen insturen). Kun je een sensor even niet lezen, stuur dan "quality": "no_response" met "value": null.

De regelaar uitlezen#

controller.protocol zegt hoe je de regelaar uitleest. controller.connection en het address van elke sensor hebben de vorm van dat protocol. Nu is dat altijd Modbus; er kunnen protocollen bij komen. Ken je het protocol niet, lees dan niets uit en blijf pollen.

Modbus#

Bij modbus_ascii en modbus_rtu, zoals bij de Alpo:

1. Open de seriële poort met de instellingen uit connection: slave_address, baudrate, parity (E, O of N), bytesize en stopbits. timeout_ms is de wachttijd per verzoek.
2. Lees per sensor één 16-bits register op address.register, met address.function_code (3 is "read holding registers", 4 "read input registers"). signed: true betekent two's complement. Sla sensoren zonder address over.
3. Deel door 10 tot de macht decimals: ruw 614 met decimals: 1 is 61,4.
4. 32767, -32768, 65535 of -9999 betekent "geen sensor": stuur sensor_fault zonder waarde.
5. Buiten plausible_min en plausible_max: stuur de waarde met out_of_range.
6. Geen antwoord: stuur no_response zonder waarde.

Bij de OEG KSW-regelaars (KSW-E, KSW en KS2W) zitten T1 tot en met T6 op registers 38 tot en met 43, R1 op 57, R2 op 58 en R3 op 31, allemaal met één decimaal, signed en functiecode 3.

Lees je je sensoren anders uit, dan negeer je controller en address en gebruik je alleen sensor, type, category, unit en het plausibele bereik. Zie Je eigen BoilerBuddy bouwen.