Ana içeriğe geç

ADR-009: Raw vs Parsed Template Mimarisi

DurumKabul Edildi
Tarih2026-02
Karar VerenGüçlü Ceyhan

Baglam​

Zeus 2.0, farkli marka ve model Modbus cihazlarini destekler: inverterler (Huawei, Sofar, Sungrow vb.), enerji analorleri, meteoroloji istasyonlari. Her cihaz modeli farkli Modbus register haritasina sahiptir.

Sorunlar:

  • Yeni cihaz modeli deestegi: Her yeni marka/model icin ESP32 firmware degisikligi mi gerekecek?
  • Register haritasi farkliliklari: Ayni bilgi (ornegin anlik guc) farkli modellerde farkli register adreslerinde
  • Veri donusumu: Bazi register'lar olcekleme (scale factor), byte sirasi (endianness), birlestirme (32-bit = 2x16-bit) gerektirir
  • Saha guncellemesi: Firmware OTA ile gonderiliyor — her cihaz modeli icin firmware degistirmek operasyonel yuk

Karar​

Iki mod desteklenir — gateway tipi (Standard veya Raw) belirler:

Standard Gateway (Template ESP32'de islenir)​

ESP32 firmware template JSON'u icerir
  → Register haritasina gore Modbus okur
  → Veriyi isler (olcekleme, birlestirme)
  → Islenmis veriyi MQTT ile publish eder
  → Backend dogrudan kaydeder

Raw Gateway (Template backend'de islenir)​

ESP32 ham register degerlerini okur
  → Raw byte verilerini MQTT ile publish eder
  → Backend template JSON'a gore parse eder
  → Islenmis veriyi kaydeder

Template Dosya Formati (JSON)​

{
  "model": "sofar-ktl-x",
  "manufacturer": "Sofar Solar",
  "device_type": "inverter",
  "registers": [
    {
      "name": "active_power",
      "address": 0x0485,
      "length": 2,
      "data_type": "uint32",
      "scale": 0.01,
      "unit": "kW",
      "group": "power"
    }
  ]
}

Alternatifler​

Sadece ESP32'de parsing (Standard only)​

  • Artilari: Dusuk MQTT trafigi (sadece islenmis veri), backend basit
  • Eksileri: Her yeni cihaz modeli icin firmware guncelleme gerekir, template degisikligi OTA gerektirir
  • Red nedeni: Yeni cihaz modeli eklemek icin tum gateway'lere OTA gondermek operasyonel olarak agir

Sadece backend'de parsing (Raw only)​

  • Artilari: ESP32 firmware'i jenerik — hic degistirmeden yeni cihaz destegi, tum logic backend'de
  • Eksileri: MQTT trafigi yuksek (ham register verileri), backend CPU yuku artar, agi daha yogun kullanir
  • Red nedeni: Yuzlerce cihazdan ham veri gonderilmesi MQTT ve backend uzerinde gereksiz yuk olusturur

Scripting (Lua/MicroPython) ESP32 uzerinde​

  • Artilari: Esnek, firmware degistirmeden script guncellenebilir
  • Eksileri: ESP32'de bellek/performans kisitlamalari, interpreter overhead, guvenlik riski (kod enjeksiyonu)
  • Red nedeni: ESP32 kaynaklarinda interpreter calistirmak performans ve guvenlik riski

Gerekce​

Iki modlu mimari su avantajlari sundu:

  1. Standard mod — performans: Bilinen ve stabil cihaz modelleri icin template ESP32'de islenir, dusuk MQTT trafigi, backend yuku minimum
  2. Raw mod — esneklik: Yeni veya legacy cihaz modelleri icin ESP32 firmware guncellemesi gerekmez — backend'e yeni template JSON eklemek yeterli
  3. Template dosyalari JSON: Kolay olusturulur, versiyonlanir, dosya sistemi uzerinden yonetilir
  4. Gecis esnekligi: Bir cihaz modeli Raw mod ile hizla desteklenir, template olgunlasinca Standard moda gecirilebilir
  5. Firmware bagimsizligi: Raw mod'daki gateway'ler jenerik firmware calistirir — marka/model farketmez

Sonuclar​

Olumlu​

  • Yeni cihaz modeli destegi saatler icinde eklenebilir (Raw mod ile)
  • Mevcut stabil modeller icin optimize performans (Standard mod)
  • Template JSON dosyalari versiyon kontrolunde — degisiklik takibi kolay
  • ESP32 firmware'i iki modda da calisabilir — deployment esnekligi
  • Backend template parse edici yeniden kullanilabilir — birkac satir kod ile yeni model

Olumsuz​

  • Iki ayri pipeline bakimi: Standard ve Raw mod icin farkli veri isleme akislari — kod tekrari riski (ortak katman ile minimize edilmis)
  • Raw mod MQTT trafigi: Ham register verileri islenmis veriye gore daha buyuk — bant genisligi maliyeti
  • Template senkronizasyonu: Standard mod'da ESP32'deki template ile backend'deki template uyumlu olmali — versiyon uyusmazligi hatalara yol acar
  • Test karmasikligi: Her iki mod icin ayri test senaryolari gerekir