Sofar Inverterler

Sofar Solar, gunes enerjisi invertorleri ve enerji depolama sistemleri ureten uluslararasi bir firmadır. Zeus 2.0, Sofar'in hibrit ve string invertor serilerini destekler.

Desteklenen Modeller

HYD 3-6K — Hibrit Invertor

Kullanim alani: Konut ve kucuk olcekli ticari tesisler, bataryali sistemler

HYD serisi hibrit invertor, gunes panellerinden (PV) gelen DC gucu AC'ye cevirirken ayni zamanda batarya sarj/desarj yonetimi yapar. Grid, PV, batarya ve yuk arasindaki enerji akisini optimize eder.

Olculen parametreler:

Kategori	Parametreler
PV Verileri	PV voltaj (V), PV akim (A), PV guc (W), gunluk PV uretimi (kWh)
Grid Verileri	Grid voltaj (V), grid akim (A), grid gucu (W), grid frekansi (Hz)
Batarya	Batarya voltaj (V), batarya akim (A), batarya gucu (W), SoC (%), sarj/desarj durumu
Yuk	Yuk gucu (W), gunluk tuketim (kWh)
Sistem	Invertor sicakligi, calisma durumu, hata kodlari

Modbus ayarlari:

Parametre	Deger
Varsayilan Slave ID	1
Baud Rate	9600
Data Bits	8
Parity	None
Stop Bits	1
Protokol	Modbus RTU

---

KTLX-G3 — String Invertor

Kullanim alani: Ticari ve endustriyel catı üstü GES (Gunes Enerjisi Santrali) sistemleri

KTLX-G3, cok MPPT girisi olan string invertor serisidir. Sadece PV uretim verilerini okur, batarya yonetimi icermez.

Olculen parametreler:

Kategori	Parametreler
PV Verileri	Her MPPT icin: voltaj (V), akim (A), guc (W)
AC Cikis	Voltaj (V), akim (A), guc (W), frekans (Hz)
Enerji	Gunluk uretim (kWh), toplam uretim (kWh)
Sistem	Invertor sicakligi, calisma durumu, hata kodlari

Modbus ayarlari:

Parametre	Deger
Varsayilan Slave ID	1
Baud Rate	9600
Data Bits	8
Parity	None
Stop Bits	1
Protokol	Modbus RTU

Modbus Register Gruplari

Sofar invertorlerin register haritasi asagidaki polling gruplari ile organize edilir:

Grup	Aralik	Icerik
realtime	5s	PV voltaj/akim/guc, grid voltaj/akim/guc, batarya durumu
energy_kwh	60s	Gunluk/toplam enerji sayaclari
bms_identity	24h	Batarya seri numarasi, SoH, kapasite
fault_status	10s	Hata kodlari ve uyari bayraklari

Sofar Fault Map

Sofar invertorlerin hata kodlari 5 kategoride siniflandirilir:

Kategori	Aciklama	Ornek Hatalar
Grid Fault	Sebeke kaynakli hatalar	Asiri voltaj, dusuk voltaj, frekans sapma, anti-islanding
DC Fault	PV ve DC taraf hatalari	Izolasyon direnci dusuk, DC asiri akim, PV string arasi fark
System Fault	Invertor dahili hatalar	Asiri sicaklik, fan ariza, EEPROM hatasi, dahili iletisim
Battery Fault	Batarya hatalari (HYD)	Batarya asiri voltaj/dusuk voltaj, BMS iletisim kaybı, asiri sicaklik
Comm Fault	Iletisim hatalari	Modbus timeout, CRC hatasi, gateway baglanti kaybı

Her hata kodu bir bit maskesi olarak register'dan okunur ve template'de tanimli fault map ile insan tarafindan okunabilir metne donusturulur.

Grid Protection Erken Uyari Sistemi

Sofar invertorlerin grid koruma parametreleri izlenerek erken uyari alarmlari olusturulabilir:

Parametre	Normal Aralik	Uyari Esigi	Aciklama
Grid Voltaj	220V +/- %10	198V veya 242V	Voltaj sinir degerlerine yaklasiyorsa uyari
Grid Frekans	50Hz +/- 0.5Hz	49.6Hz veya 50.4Hz	Frekans sinir degerlerine yaklasiyorsa uyari
Izolasyon Direnci	> 500k ohm	< 100k ohm	Izolasyon direnci duserse PV sistem toprak arizasi riski
DC/AC Oranı	< 1.3	> 1.25	Asiri clipping olabilir, panel dizilimi kontrolu gerekir

Bu uyarilar backend alarm sisteminde tanimlanir ve ilgili esikler gecildiginde bildirim gonderilir.

Marka/Model Tespiti

Sofar invertorlerinin dedicated bir marka/model register'i yoktur. Cihaz tespiti, seri numarasindan cikarilir:

• Seri numarasi belirli register araliginda saklanir
• Seri numarasinin ilk karakterleri model ailesini belirtir
• Template eslestirme backend tarafinda seri numarasi parse edilerek yapilir
• Gateway ilk baglantiginda seri numarasini okur ve backend'e bildirir, uygun template otomatik atanir

Ornek: SP2ES... ile baslayan seri numarasi, HYD serisine ait 10kW modelini isaret eder.

Bilinen Tuzaklar

Peak-Shaving Modu

Sofar HYD serisinde peak-shaving (tepe tirpanlama) modu, Modbus register'inda time-sharing mode olarak kodlanmistir ve degeri 2'dir.

Mode Register Degerleri:
0 = Self-use (oz tuketim)
1 = Time-of-use (zaman tarifeli)
2 = Peak-shaving (tepe tirpanlama)  ← Dokumanasyonda "time-sharing" olarak gecer

Bu isimlendirme karmasikligi, Sofar'in Cince dokumantasyonunun Ingilizce cevirisinden kaynaklanir. Template ve backend kodunda mode=2 icin peak_shaving etiketi kullanilmalidir.

Register Byte Order

Sofar invertorleri Big Endian (Modbus standardi) byte order kullanir. 32-bit degerler icin register sirasi: [High Word][Low Word].

Batarya Iletisimi

HYD serisinde batarya BMS ile iletisim, invertorün kendi dahili bus'i uzerinden yapilir. Modbus uzerinden sadece invertorun raporladigi batarya degerleri (SoC, voltaj, akim) okunabilir — dogrudan BMS'e Modbus ile erisilemez.

---

Power Register Kolonlaştırma (Issue #237)

Daha önce Sofar power verileri (PV1/PV2 voltage/current/power, battery voltage/current/SoC/SoH) device_measurements.extra_metadata JSONB kolonu içinde saklanıyordu. Bu yapı sorgu performansını ve continuous aggregate üretimini olumsuz etkiliyordu.

Migration Dizisi

Migration	İşlem
0031	device_measurements'a Sofar power kolonları eklendi (nullable)
0032	extra_metadata JSONB içinden mevcut veri yeni kolonlara backfill edildi
0033	TimescaleDB continuous aggregate'leri yeni kolonları içerecek şekilde genişletildi
0034	extra_metadata içinden Sofar power alanları temizlendi (cleanup)

Bu expand → backfill → contract pattern'i 4 ayrı release'e bölünerek uygulandı; her adım production'da doğrulandıktan sonra bir sonraki adıma geçildi.

Yeni Kolonlar

Kategori	Alanlar
PV1	sofar_pv1_voltage, sofar_pv1_current, sofar_pv1_power
PV2	sofar_pv2_voltage, sofar_pv2_current, sofar_pv2_power
Batarya	sofar_bat_voltage, sofar_bat_current, sofar_bat_soc, sofar_bat_soh

Dashboard Refactor

Frontend InverterDashboard bileşeni JSONB path query'leri (extra_metadata->>'pv1_power') yerine doğrudan kolon erişimi kullanır. PV/battery/grid SoC chart ayrı bir component'e refactor edildi.

---

Fault Code Bit-level Decode

Sofar inverter'lar 5 ayrı fault register kullanır (fault_code_1..fault_code_5). Her register 16-bit; toplam 80 bit fault flag taşır. Bit pozisyonlarının her biri ID01-ID60 arası benzersiz fault ID'sine karşılık gelir.

Fault Map Yapısı

frontend/src/lib/sofarFaultMap.ts — UI tarafı bit pozisyonu ↔ insan tarafından okunabilir mesaj eşlemesi:

{
  register: 'fault_code_1',
  bit: 0,
  id: 'ID01',
  message: 'Grid Over Voltage',
  severity: 'error',  // info | warning | error | critical
}

Severity sınıfları:

Severity	Anlam	Örnek
info	Bilgilendirici, müdahale gerekmez	Grid bağlantısı yeniden kuruldu
warning	İzlenmeli	Sıcaklık yüksek (henüz limit altı)
error	Müdahale gerekli	İzolasyon direnci düşük
critical	Acil müdahale	DC arc fault, batarya yangın riski

InverterStatusCard Dialog

UI'da fault ID'ye tıklandığında dialog açılır:

• Register adresi (fault_code_3)
• Bit pozisyonu (bit 7)
• Raw değer (0x0080)
• Severity badge (renk kodlu)
• Açıklama (kullanıcı dilinde)

Backend Karşılığı

backend/app/features/alarms/sofar_fault_map.py — backend tarafında alarm değerlendirmesi için kullanılır. Sofar template prefix entegrasyonu Faz 1 ve Faz 2'de tamamlandı. UI ile aynı bit haritasını paylaşır (tek kaynak: JSON template).

---

BMS Identity Polling (Issue #212)

DeviceBmsIdentity Modeli

Sofar HYD 13 inverter, batarya pack ve cell sayısı, üretici ve kapasite bilgilerini Modbus register grup 5.10.1-5.10.6'da yayınlar.

Alan	Açıklama
BMS Pack count	Bağlı batarya pack sayısı
Cell count	Toplam hücre sayısı
Manufacturer	Batarya üretici kodu
Capacity (Ah)	Nominal kapasite
Manufacture date	Üretim tarihi
Last polled at	Son okuma zamanı

Polling Akışı

• Daily auto-check: 04:00 UTC (Celery beat task bms_identity.daily_check)
• Manuel trigger: Backend → MQTT cmd/read_group → ESP32 → Modbus okuma → MQTT response → backend update
• Audit log: Değişiklik tespit edilirse device_bms_audit_log append-only

Detay için bkz. Celery Görevleri.

---

TLS Heap Corruption Fixes (Issue #215)

ESP32 firmware tarafında Sofar inverter ile uzun süreli iletişim sırasında düşük olasılıkla heap corruption gözlemlendi. Üç ayrı düzeltme uygulandı:

1. mbedtls_ssl_free() Bypass

mbedtls_ssl_free() çağrısı Core 1'de race condition'a sebep oluyordu (TLS context paylaşımı). Çözüm: free işlemi atlandı, context object pool'da yeniden kullanılır. Heap fragmentation Core 1 task döngüsüyle dengelenir.

2. UseInternalTask::NO Konfigürasyonu

ArduinoMQTTClient default olarak internal task spawn eder. Sofar inverter'in kararsız Modbus yanıtları sırasında bu task ile çakışma LoadProhibited exception veriyordu. Çözüm: UseInternalTask::NO ile MQTT loop ana task'a alındı.

3. Shared TLS Client Cleanup

HTTPS sertifika rotasyonu sırasında shared TLS client referansları temizlenmiyordu. Çözüm: rotasyon sonrası weak_ptr::expired() kontrolü ile dangling pointer engellendi.

---

interval=0 Poll-Once Semantik (Issue #208)

Block group config'inde intervalMs=0 özel anlam taşır: bir kez oku, sonra atla. Bu, kalibrasyon register'ları (CT ratio, BMS identity) ve nadiren değişen yapılandırma değerleri için kullanılır.

Kullanım

{
  "groupId": "bms_identity",
  "intervalMs": 0,
  "blocks": [...]
}

Davranış

• İlk polling döngüsünde okunur
• Sonraki döngülerde atlanır (poll list'te tutulur ama execute edilmez)
• Manuel olarak cmd/read_group MQTT komutuyla tetiklenebilir
• Daily Celery task ile günlük otomatik refresh

Uygulanan Template'ler

• SOFAR-HYD-3-6K — bms_identity grubu (intervalMs=0)
• SOFAR-KTLX-G3 — static_config grubu (intervalMs=0)

Pil Verileri Starvation'ı Önleme

Daha önce bms_identity grubu 24 saatte bir okunduğunda (intervalMs=86400000), realtime polling döngüsünde "wait for next interval" mantığı diğer grupları geciktirebiliyordu. intervalMs=0 ile bu grup polling scheduler'dan tamamen çıkarılır; realtime ve fault_status grupları starve olmaz.