Yeni Cihaz Ekleme Rehberi

Bu rehber, Zeus 2.0'a yeni bir Modbus RTU cihazi entegre etmek icin adim adim sureci aciklar. Yeni cihaz destegi eklemek icin firmware degisikligi gerekmez — sadece bir JSON template dosyasi olusturmak yeterlidir.

On Gereksinimler

Baslamadan once asagidakilerin hazir oldugunden emin olun:

• Cihazin Modbus register haritasi (uretici dokumanasyonu)
• Desteklenen function code'lar (genellikle FC 3 ve/veya FC 4)
• Veri tipleri (uint16, int16, uint32, float32 vb.)
• Scale factor bilgileri (bazi register'lar 0.1, 0.01 gibi carpanlar kullanir)
• Cihazin varsayilan Modbus ayarlari (Slave ID, baud rate, parity)
• Fiziksel olarak test edilebilecek bir cihaz (veya simulator)

Adim 1: Cihaz Modbus Dokumanini Inceleyin

Uretici tarafindan saglanan Modbus register haritasini detayli inceleyin. Asagidaki bilgileri cikartin:

Register Adresleme Kontrolu

Kritik: Uretici dokumaninin 0-based mi yoksa 1-based mi adresleme kullandığını belirleyin.

• Eger dokuman "Register 1" ile basliyorsa → 1-based (template'de 1 cikarin)
• Eger dokuman "Register 0" ile basliyorsa → 0-based (template'de oldugu gibi kullanin)

Zeus template'leri her zaman 0-based adresleme kullanir.

Byte Order Kontrolu

Cogu Modbus cihazi Big Endian (standart Modbus) kullanir. Ancak bazi cihazlar, ozellikle 32-bit degerler icin farkli byte order kullanabilir:

Byte Order	Aciklama	Ornek (0x12345678)
Big Endian (AB CD)	Standart Modbus, yuksek byte once	[0x1234][0x5678]
Little Endian (CD AB)	Dusuk word once	[0x5678][0x1234]
Mid Big Endian (BA DC)	Byte swap	[0x3412][0x7856]
Mid Little Endian (DC BA)	Word ve byte swap	[0x7856][0x3412]

Byte order bilgisi genellikle uretici dokumaninda belirtilir. Belirtilmediyse Big Endian varsayilir ve raw mode ile test edilerek dogrulanir.

Veri Tipleri

Her register icin veri tipini belirleyin:

Veri Tipi	Register Sayisi	Deger Araligi
uint16	1	0 — 65535
int16	1	-32768 — 32767
uint32	2	0 — 4294967295
int32	2	-2147483648 — 2147483647
float32	2	IEEE 754 kayan nokta

Adim 2: Template JSON Dosyasi Olusturun

Asagidaki yapiyi temel alarak cihaziniz icin bir template olusturun:

{
  "templateId": "marka-model",
  "manufacturer": "Marka Adi",
  "model": "Model Adi",
  "defaultSlaveId": 1,
  "defaultBaudRate": 9600,
  "byteOrder": "big_endian",
  "groups": [
    {
      "groupId": "realtime",
      "intervalMs": 5000,
      "blocks": [
        {
          "startAddress": 0,
          "count": 20,
          "functionCode": 3
        }
      ],
      "fields": [
        {
          "name": "voltage_l1",
          "offset": 0,
          "dataType": "float32",
          "scaleFactor": 1.0,
          "unit": "V"
        },
        {
          "name": "voltage_l2",
          "offset": 2,
          "dataType": "float32",
          "scaleFactor": 1.0,
          "unit": "V"
        },
        {
          "name": "current_l1",
          "offset": 4,
          "dataType": "float32",
          "scaleFactor": 1.0,
          "unit": "A"
        },
        {
          "name": "active_power_total",
          "offset": 6,
          "dataType": "float32",
          "scaleFactor": 0.001,
          "unit": "kW"
        }
      ]
    },
    {
      "groupId": "energy_kwh",
      "intervalMs": 60000,
      "blocks": [
        {
          "startAddress": 100,
          "count": 10,
          "functionCode": 3
        }
      ],
      "fields": [
        {
          "name": "active_energy_import",
          "offset": 0,
          "dataType": "uint32",
          "scaleFactor": 0.01,
          "unit": "kWh"
        },
        {
          "name": "reactive_energy_import",
          "offset": 2,
          "dataType": "uint32",
          "scaleFactor": 0.01,
          "unit": "kVArh"
        }
      ]
    }
  ]
}

Polling Gruplari Secimi

Cihazin olctugu parametrelere gore uygun polling gruplari olusturun:

Grup ID	Kullanim	Onerilen Aralik
realtime	Voltaj, akim, guc, guc faktoru	5s
power_totals	Toplam guc, frekans	5s
energy_kwh	Enerji sayaclari	60s
step_values	Kompanzasyon kademe degerleri	30s
ct_ratio	CT/PT yapilandirma	86400s (24h)
fault_status	Hata kodlari, uyari bayraklari	10s
bms_identity	Batarya/cihaz kimlik bilgisi	86400s (24h)

Not: Her polling grubundaki toplam register sayisi olabildiğince az tutulmalidir. Gereksiz yere buyuk count degeri kullanmak, Modbus bus'ini yavaslatan buyuk yanit paketlerine neden olur.

Field Isimlendirme Konvansiyonlari

Tutarli isimlendirme icin asagidaki kurallara uyun:

voltage_l1, voltage_l2, voltage_l3          # Faz voltajlari
voltage_l12, voltage_l23, voltage_l31       # Hat voltajlari
current_l1, current_l2, current_l3          # Faz akimlari
active_power_l1, active_power_total         # Aktif guc
reactive_power_l1, reactive_power_total     # Reaktif guc
apparent_power_l1, apparent_power_total     # Gorunen guc
power_factor_l1, power_factor_total         # Guc faktoru
frequency                                   # Frekans
active_energy_import, active_energy_export  # Aktif enerji
reactive_energy_import                      # Reaktif enerji
thd_voltage_l1, thd_current_l1             # Harmonik bozulma

Adim 3: Template Dosyasini Yukleyin

Olusturdugunuz template JSON dosyasini backend'e yukleyin:

1. Template dosyasini backend templates dizinine kopyalayin
2. Backend API uzerinden template'i kaydedin
3. Template'in veritabaninda gorunduğunu dogrulayin

Template yuklendikten sonra, yeni cihazlar bu template ile eslestirilebilir hale gelir.

Adim 4: Raw Mode ile Test Edin

Yeni template'i uretim ortaminda kullanmadan once raw mode ile test edin:

1. ESP32 gateway'i cihaza RS-485 uzerinden baglayın
2. Gateway'i raw mode'a alin
3. Raw mode'da gateway, template'i parse etmeden ham register degerlerini hex olarak gonderir

{
  "slaveId": 1,
  "addr": 0,
  "count": 20,
  "data": "43E6800043E5999A43E700004140000041400000..."
}

4. Hex verileri manuel olarak decode edin ve cihaz ekranindaki degerlerle karsilastirin
5. Eger degerler uyusmuyorsa:
   • Byte order'i kontrol edin (Big Endian / Little Endian)
   • Register offset'lerini kontrol edin (0-based / 1-based)
   • Scale factor'leri kontrol edin
   • Veri tiplerini kontrol edin

Ornek: Float32 Decode

Hex 43E68000 degerini float32 olarak decode etmek:

43E68000 (hex)
= 0 10000111 11001101000000000000000 (binary)
= +1 × 2^(135-127) × 1.80078125
= 460.0 (ondalik)

Bu deger cihazin ekranindaki voltaj degeriyle uyusmalidir (ornegin 460.0V).

Adim 5: Standard Mode ile Dogrulama

Raw mode testi basarili olduktan sonra:

1. Gateway'i standard mode'a gecirin
2. Template eslestirmesini yapin
3. Backend loglarinda parse edilen degerleri kontrol edin
4. Dashboard'da degerlerin dogru gorunduğunu dogrulayin
5. Tum polling gruplarinin calıstığını ve verilerin dogru aralikta geldiğini dogrulayin

Adim 6: Production'a Gecis

Tum testler basarili olduktan sonra:

1. Template dosyasini production backend'e yukleyin
2. Cihazi ilgili tenant ve gateway'e tanimlayın
3. Standard mode'da calismaya baslayin
4. Ilk 24 saat boyunca verileri yakindan izleyin
5. Alarm kurallarini tanimlayin

Sik Karsilasilan Sorunlar

Veri Okunamiyor (Timeout)

• RS-485 kablolama kontrolu: A/B ters mi?
• Slave ID dogru mu?
• Baud rate eslesiyormu?
• Termination direnci takildi mi (son cihazda)?
• Kablo uzunlugu cok fazla mi?

Yanlis Deger Okunuyor

• Byte order kontrol edin (Big vs Little Endian)
• Register offset'i 1 eksik/fazla olabilir (0-based vs 1-based)
• Scale factor yanlis olabilir (0.1 yerine 0.01 vb.)
• Veri tipi yanlis olabilir (uint16 yerine float32 vb.)

Bazi Register'lar 0 (Sifir) Donuyor

• Cihaz o parametreyi olcmuyor olabilir (CT/PT baglanmamis)
• Function code yanlis olabilir (FC 3 yerine FC 4 deneyin)
• Register adresi o model icin gecerli olmayabilir

Polling Yavaslıyor

• Ayni bus uzerinde cok fazla cihaz olabilir
• count degerleri gereksiz yere buyuk olabilir
• Polling intervalleri cok kisa olabilir
• RS-485 bus uzerindeki toplam istek sayisini hesaplayin: her istek ~50-100ms surer

Onerı

Yeni bir cihaz entegre ederken, once sadece realtime grubu ile baslayin. Degerler dogrulandiktan sonra diger gruplari ekleyin. Bu yaklasim, sorun gidermeyi kolaylastirir.