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

Cihaz Sihirbazında Rol Seçimi (device_role)

Bir template hazır olduktan sonra cihazı platforma "Yeni Cihaz Ekle" sihirbazı ile tanımlarsınız (Sidebar → Cihazlar → Yeni Cihaz Ekle). Bu sihirbazın en kritik adımlarından biri Cihaz Rolü seçimidir: bu alan, Zeus 2.0'ın cihazı nasıl yorumlayacağını (üretim mi, tüketim mi, kesici mi), hangi dashboard kartlarına gireceğini ve hangi tarifelerin uygulanabilir olacağını belirler.

Sihirbaz sırası (dialog içi)

Cihaz dialogu açıldığında (bölge → alt bölge → gateway seçildikten sonra) alanlar şu sırayla gelir:

1. Cihaz Şablonu (Template) — hangi register haritasının kullanılacağı.
2. Modbus Ayarları (Slave ID, Okuma Aralığı) — şablonun hemen ardından gelir (Cihaz Rolü'nden önce). Bu alanlar şablon seçilse de elle değiştirilebilir.
3. Üst Cihaz (Opsiyonel — Hiyerarşi) — SLD ve LOTO için üst/alt cihaz ilişkisi.
4. Cihaz Adı — cihazın Zeus içindeki adı.
5. Cihaz Rolü — bu bölümün konusu (aşağıda ayrıntılı).
6. Üretici / Model — Cihaz Rolü'nden sonra gelir. Bir şablon seçtiyseniz bu iki alan otomatik dolar ve salt-okunur (gri) olur.

Otomatik dolum (template seçince rol kendiliğinden gelir)

1. adımda bir şablon seçtiğinizde, o şablonun tanımlı olduğu Üretici, Model, Cihaz Rolü, Slave ID ve Okuma Aralığı alanları otomatik dolar. Yani doğru şablonu seçtiyseniz rolü genellikle elle değiştirmenize gerek kalmaz.

• Manuel giriş (şablon kullanma) seçeneğini işaretlerseniz Üretici, Model ve Cihaz Rolü temizlenir ve bu alanları elle doldurmanız gerekir. (Bu seçenek listede her gateway tipinde görünür; ancak MQTT gateway'de bir şablon seçmeden kaydetmeye çalışırsanız kayıt bloklanır ve şablon seçmeniz istenir — MQTT'de şablon zorunludur.)
• Otomatik gelen rolü yine de elle değiştirebilirsiniz — kaydetmeden önce doğru rolün seçili olduğundan emin olun.

"Cihaz Rolü" alanı — bilmeniz gereken her şey

Soru	Cevap
Bu alan ne?	Cihazın Zeus 2.0 içindeki işlevsel rolü. Cihazın nasıl yorumlanacağını (üretim / tüketim / kesici / ölçüm), hangi dashboard kartlarına gireceğini ve hangi tarifelerin uygulanabileceğini belirler.
Zorunlu mu?	Form üzerinde zorunlu işaretlidir (4. Cihaz Rolü *). Teknik olarak boş kaydedilebilir; ancak rolsüz cihaz hiçbir rol tabanlı davranışa (üretim KPI'sı, tarife, açma/kapama) girmez. Bu yüzden mutlaka doğru rolü seçin.
Ne seçeceğim?	Cihazın fiziksel türüne uygun seçeneği (aşağıdaki tablo). Örn. GES invertörü → İnvertör, elektrik sayacı → Sayaç, TMŞ → Kesici.
Değeri NEREDEN bulurum?	Cihazın türünden: sahadaki fiziksel cihaz nedir? Bir şablon seçtiyseniz rol otomatik gelir (şablon doğru tanımlıysa değiştirmeyin).
Boş / yanlış seçersem ne olur?	Boş bırakırsanız cihaz rolsüz kalır, sınıflandırılmaz. Yanlış rol ise davranışı bozar: bir invertörü "Yük" olarak eklerseniz üretim dashboard'una girmez ve üretim tarifesi uygulanamaz; bir sayacı "İnvertör" seçerseniz tüketim yerine üretim gibi yorumlanır. Rol, cihaz kaydedildikten sonra düzenleme ekranından değiştirilebilir.

Rol seçenekleri (11 değer)

Teknik değer	TR etiket	Ne zaman bunu seç
inverter	İnvertör	GES invertörü / üretim cihazı. Üretim ölçümlerine yazılır, üretim dashboard KPI'sına girer, üretim tarifesi uygulanabilir. Seçince ek Telemetri tipi alanı açılır (aşağıya bakın).
charger	Şarj İstasyonu	EV (elektrikli araç) şarj istasyonu. Oturum/enerji verileri OCPP üzerinden işlenir.
meter	Sayaç	Elektrik/enerji sayacı. Düzenleme ekranında Ana Sayaç işaretlenirse tüketim tarifesi uygulanabilir.
analyzer	Analizör	Şebeke/enerji analizörü (voltaj, akım, güç, harmonik ölçen cihaz).
breaker	Kesici (TMŞ)	Termik-manyetik şalter / kesici. Açılıp kapatılabilir (Açma/Kapama özelliği); SLD ve LOTO'da enerji kesme noktası.
relay	Röle	Koruma / kontrol rölesi.
mcc	MCC	Motor Kontrol Merkezi. Açılıp kapatılabilir.
panel	Pano	Dağıtım panosu. Açılıp kapatılabilir.
generator	Jeneratör	Yedek/ana jeneratör. Açılıp kapatılabilir.
transformer	Trafo	Güç trafosu.
load	Yük	Genel tüketim / yük noktası (başka role uymayan tüketiciler).

Açma/Kapama (switchable) rolleri

Kesici (TMŞ), MCC, Pano ve Jeneratör rolleri için sihirbazın altındaki "Açma/Kapama Özellikleri" bölümünden "Bu cihaz açılıp kapatılabilir" kutusunu işaretleyip başlangıç durumunu (Açık / Kapalı) belirleyebilirsiniz. Bu bilgi SLD (Tek Hat Şeması) ve LOTO akışlarında kullanılır.

Hangi rolü seçmeliyim? (karar diyagramı)

İnvertör rolü — üretim şeffaflığı

Cihaz Rolü = İnvertör seçtiğinizde sihirbazda "Bu bir üretim cihazıdır" başlıklı bir bilgi kutusu belirir. Bu kutu, invertörünüzün verisinin platformda nasıl işleneceğini açıkça anlatır (üretim şeffaflığı):

• Verileri üretim ölçümlerine yazılır (veriş/export enerji, PV gücü; hibrit ise batarya SoC (şarj durumu) ve batarya gücü de dahil).
• Dashboard üretim KPI'sına (GES sayısı + toplam üretim) dahil edilir; batarya verisi varsa cihaz BESS (Batarya Enerji Depolama Sistemi) olarak otomatik tanınır.
• Üretim tarifesi (FiT / mahsup) uygulanabilir; tüketim tarifesi uygulanmaz.
• Master invertör ve üretim tarifesi, cihaz kaydedildikten sonra düzenleme ekranından ayarlanır (aşağıdaki "Kaydettikten sonra" bölümüne bakın).

Telemetri tipi — üretimin doğru toplanması için

İnvertör rolünde ayrıca opsiyonel bir Telemetri tipi açılır listesi gelir: Bağımsız (standalone) vs Agregatör — master (aggregate_master). Bu ayar, paralel invertörlü kurulumlarda toplam üretimin çift sayılmasını veya sıfır görünmesini önler.

• Bağımsız (standalone): her invertör kendi üretimini ayrı raporlar (örn. Huawei SUN2000). Üretim doğrudan toplanır.
• Agregatör — master (aggregate_master): paralel sistemde tek bir "master" invertör tüm string/slave'lerin toplamını raporlar (örn. SOFAR paralel).

Bu seçimin tamamı ve karar ağacı için ayrı bir sayfa var: İnvertör Telemetri Tipi (Topoloji). Emin değilseniz boş bırakın (— Sınıflandırılmamış); bu güvenli varsayılandır.

Master'sız (standalone) invertör de dashboard'da görünür

Artık bir invertör "master" işaretli olmasa bile üretimi Üretim & Depolama Özeti ve GES Getirisi kartlarında görünür. Ölçüm sayfasındaki "Tüm Cihazlar" çoklu-seri grafiği ve dashboard etkileri için bkz. Üretim Ölçümleri.

Şarj İstasyonu rolü

Cihaz Rolü = Şarj İstasyonu seçtiğinizde kısa bir bilgi notu çıkar: "Şarj istasyonu — oturum/enerji verileri OCPP üzerinden işlenir." Yani şarj istasyonları Modbus template'i yerine OCPP protokolü ile yönetilir; oturum başlatma/durdurma ve enerji ölçümleri OCPP mesajlarından gelir.

Kaydettikten sonra: Master İnvertör, Ana Sayaç ve tarife

Bazı ayarlar cihaz oluşturulurken değil, kaydedildikten sonra düzenleme ekranından yapılır. Cihazı kaydedip listeden Düzenle ile açtığınızda role göre şu kontroller çıkar:

• İnvertör rolünde → "Master İnvertör" anahtarı görünür.
  • Açık (is_master = true) → Üretim Tarifesi açılır listesi etkinleşir (FiT/mahsup tarifesi atayabilirsiniz).
  • Kapalı (is_master = false) → cihaz slave kabul edilir; bir bilgi notu gösterilir (üretimi master üzerinden raporlanır, çift sayım önlenir).
• İnvertör dışı rollerde → "Ana Sayaç" anahtarı görünür.
  • Açık (is_main_meter = true) → Tüketim Tarifesi açılır listesi etkinleşir.
• Yukarıdaki koşullar sağlanmıyorsa tarife bölümü gösterilmez.

Rolü sonradan değiştirmek

Cihaz rolünü invertörden başka bir role (veya tersi) çevirirseniz, role bağlı alanlar da değişir: örneğin invertör değilken Telemetri tipi kaydedilmez (otomatik temizlenir). Rol değişikliğinden sonra düzenleme ekranındaki Master/Ana Sayaç ve tarife ayarlarını gözden geçirin.

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.