Zeus 2.0 — OCPP 1.6J Entegrasyon Rehberi

Versiyon: 1.0 (Faz 2 release) Hedef Kitle: Charger üreticileri (Beny, vb.), saha teknisyenleri, OCPP entegratörleri Dil: Türkçe (teknik terimler İngilizce korunmuştur)

Bu doküman, OCPP 1.6J protokolü konuşan tüm AC/DC charger'ların Zeus 2.0 Energy Management System'e bağlanma kontratını tanımlar. İlk doğrulanmış charger modeli Beny BCP-AT2N-P 22kW AC'dir; ancak içerik tüm OCPP 1.6J uyumlu cihazlar için geçerlidir.

1. Genel Bakış

Zeus 2.0, OCPP 1.6J Central System (CSMS) rolüyle çalışır. Charger'lar (Charge Point — CP) Zeus'a WebSocket Secure (WSS) üzerinden bağlanır ve JSON-formatlı OCPP mesajları değiştirir.

Özellik	Değer
Protokol	OCPP 1.6J (JSON over WebSocket)
Transport	WSS (TLS at nginx reverse proxy)
Subprotocol header	`ocpp1.6`
Mesaj formatı	JSON-RPC benzeri `[MessageTypeId, UniqueId, Action, Payload]`
Multi-tenant	Evet — her charger bir `tenant_id` ile ilişkilendirilir

Desteklenen Protokol Versiyonları

Versiyon	Durum
OCPP 1.6J	Production — Faz 2 itibarıyla tam destek
OCPP 2.0.1	Yakında — endpoint stub mevcut, handshake `1011` ile kapatılır

Desteklenen Feature Profile'lar (OCPP 1.6J)

Core — BootNotification, Heartbeat, StatusNotification, Authorize, StartTransaction, StopTransaction, MeterValues, DataTransfer
FirmwareManagement — UpdateFirmware, FirmwareStatusNotification, GetDiagnostics, DiagnosticsStatusNotification
LocalAuthList — GetLocalListVersion, SendLocalList
Reservation — ReserveNow, CancelReservation
SmartCharging — SetChargingProfile, ClearChargingProfile, GetCompositeSchedule

İlk Doğrulanmış Charger

Beny BCP-AT2N-P 22kW AC (3-faz, Type 2 soket, RFID, Wi-Fi/Ethernet/4G)

2. WebSocket Endpoint'leri

Zeus iki versiyon için ayrı WebSocket endpoint sunar. Charger, kendi protokol versiyonuna uyan path'e bağlanmalıdır.

Endpoint	Versiyon	Durum
`wss://{host}/ocpp/1.6/{cpid}`	OCPP 1.6J	Production
`wss://{host}/ocpp/2.0.1/{cpid}`	OCPP 2.0.1	Stub (1011 close)

{host} — Zeus production domain (örn. ems.example.com)
{cpid} — Charge Point Identity (Zeus tarafından üretilen benzersiz cihaz kimliği)

Önemli: Path'in sonundaki trailing slash (/ocpp/1.6/) zorunludur; ardından CPID gelir. Trailing slash atlanırsa charger 404 veya 4400 ile reddedilir.

3. Charger-Side Configuration Reference

Charger'ın web UI veya konfigürasyon arayüzünde 6 alan girilmelidir. Aşağıdaki tablo Beny BCP-AT2N-P üzerinden anlatılmıştır; diğer üreticilerin alan isimleri farklı olsa da semantik aynıdır.

3.1. Beny BCP-AT2N-P UI Alanları

Beny UI Alanı	Açıklama	Örnek Değer
Central System Hostname	Zeus production domain (TLS terminator)	`ems.example.com`
Central System Port	TLS port (genellikle 443)	`443`
Charge Point Path	URL path prefix — trailing slash zorunlu	`/ocpp/1.6/`
Charge Point Identity	Zeus tarafından üretilen benzersiz CPID	`BENY-AB12CD34EF56`
Authorization Username	CPID ile birebir aynı olmak zorunda	`BENY-AB12CD34EF56`
Authorization Password	Zeus admin UI'dan üretilir, bir kez gösterilir	`<32-char random>`

3.2. Nihai Bağlantı URL'i

Yukarıdaki alanlardan oluşan tam WebSocket URL şu şekilde birleştirilir:

wss://{Hostname}:{Port}{Path}{CPID}

Örnek:

wss://ems.example.com:443/ocpp/1.6/BENY-AB12CD34EF56

3.3. CPID Format Kısıtlaması

CPID, hem URL path'inde hem de Basic Auth username olarak kullanılır. Aşağıdaki regex'e mutlaka uymalıdır:

^[A-Za-z0-9_.-]{4,40}$

İzin verilen karakterler: A–Z, a–z, 0–9, alt çizgi (_), nokta (.), tire (-)
Uzunluk: 4–40 karakter
Boşluk, Türkçe karakter, özel karakter kabul edilmez

CPID kuralı dışı ise Zeus handshake sırasında 4400 close code ile bağlantıyı reddeder.

4. Authentication

Zeus, OCPP 1.6J Security Profile 1'i destekler: HTTP Basic Auth over WSS (TLS terminator nginx katmanındadır).

4.1. HTTP Basic Auth Header

WebSocket handshake (HTTP Upgrade) isteğinde aşağıdaki header gönderilmelidir:

Authorization: Basic base64(cpid:password)

Örnek (CPID=BENY-AB12CD34EF56, password=s3cr3tP@ssw0rd123456789012345678):

Authorization: Basic QkVOWS1BQjEyQ0QzNEVGNTY6czNjcjN0UEBzc3cwcmQxMjM0NTY3ODkwMTIzNDU2Nzg=

4.2. Username = CPID Kuralı

Basic Auth username, URL path'teki CPID ile birebir aynı olmalıdır. Mismatch durumunda Zeus 4401 close code ile bağlantıyı reddeder.

URL: wss://ems.example.com/ocpp/1.6/BENY-AB12CD34EF56
Auth username: BENY-AB12CD34EF56     OK
Auth username: BENY-XX99YY99ZZ99     4401 close

4.3. Password Yönetimi

Password Zeus admin UI tarafından üretilir ve operatöre bir kez gösterilir.
Veritabanında bcrypt ile hash'lenir (cost ≥ 12).
Plain-text password Zeus loglarında, DB'de veya audit kayıtlarında asla saklanmaz.
Password'ü kaybeden operatör Zeus admin UI'dan rotate-password akışını çalıştırarak yeni password üretmelidir (eski password derhal geçersiz olur).

4.4. Rate Limit (Brute-Force Koruması)

Aynı (IP, CPID) kombinasyonu için 3 başarısız auth denemesi sonrası 60 saniye rate-limit uygulanır.
Rate-limit aktifken bağlantı 4429 close code ile reddedilir.
Sayaç Redis'te tutulur; Redis erişilemezse fail-closed davranılır (4503).

5. Subprotocol Negotiation

WebSocket handshake sırasında charger tercih edilen OCPP versiyonunu Sec-WebSocket-Protocol header'ı ile bildirir.

5.1. Önerilen Davranış

Charger handshake isteğinde aşağıdaki header'ı göndermelidir:

Sec-WebSocket-Protocol: ocpp1.6

Zeus bu header'ı kabul eder ve yanıtta aynı subprotocol ile accept(subprotocol="ocpp1.6") döner.

5.2. Header Eksikse (Vendor Compatibility)

Bazı eski/legacy charger firmware'leri bu header'ı göndermez. Zeus, RFC 6455 strict mode kullanmaz; uyumluluk için accept(subprotocol=None) ile bağlantıyı kabul eder.

Not: Bu tolerans yalnızca /ocpp/1.6/ endpoint'i içindir. OCPP 2.0.1 endpoint'i strict subprotocol gerektirir.

5.3. Yanlış Subprotocol

Charger versiyon ile endpoint uyuşmaz subprotocol gönderirse Zeus 4400 close code ile bağlantıyı reddeder:

Endpoint: /ocpp/1.6/BENY-AB12CD34EF56
Subprotocol header: ocpp2.0.1     4400 close ("Subprotocol mismatch")

6. WebSocket Close Code Reference

Charger bağlantıyı kuramadığında veya kopardığında Zeus aşağıdaki close code'lardan birini döner. Saha teknisyenleri ve üreticiler için troubleshooting referansı:

Kod	Anlam	Çözüm
1000	Normal kapanma	Yok — beklenen kapanış
1011	Sunucu iç hatası / OCPP 2.0.1 desteklenmiyor	OCPP 1.6J endpoint'ine geç (`/ocpp/1.6/`)
4400	Geçersiz CPID format veya subprotocol mismatch	CPID regex (`^[A-Za-z0-9_.-]{4,40}$`) doğrula; subprotocol `ocpp1.6` gönder
4401	Yetkisiz (yanlış password veya username ≠ CPID)	Password'ü Zeus admin UI'dan rotate et: `POST /api/ocpp/chargers/{id}/rotate-password`
4404	CPID Zeus DB'sinde yok	Admin önce charger kaydı oluşturmalı; charger eklenmeden bağlantı denemesi yapılmamalı
4429	Rate-limited (3 başarısız deneme + 60sn)	60 sn bekle, ardından doğru password ile yeniden bağlan
4503	Redis altyapı geçici erişilemez (fail-closed)	Zeus operasyon ekibine bildir; charger otomatik exponential backoff ile yeniden bağlanır

Saha tavsiyesi: Close code Zeus admin UI'da OCPP Audit Log sayfasından charger bazında izlenebilir.

7. Bağlantı LED Sinyalleri (Beny BCP-AT2N-P)

Beny BCP-AT2N-P üzerindeki status LED'i bağlantı durumunu görsel olarak iletir:

LED Davranışı	Anlam
Yeşil pulse ("nefes" efekti)	OCPP bağlı — heartbeat aktif
Yeşil 1sn ON / 1sn OFF (slow blink)	OCPP bağlanamadı — close code'a göre troubleshoot
Mavi (şarj rengi)	Aktif şarj oturumu (transaction in progress)
Kırmızı	Hata durumu — `StatusNotification.errorCode` alanını kontrol et

Diğer üretici charger'larda LED davranışları farklı olabilir; üretici dokümanına başvurun.

8. Boot Notification Sonrası Otomatik Konfigürasyon

Charger ilk bağlandığında BootNotification mesajı gönderir. Zeus Accepted döndüğünde, arka planda 10 adet ChangeConfiguration çağrısı yaparak charger'ı standart Zeus profiline çeker.

8.1. Otomatik Uygulanan Konfigürasyon Anahtarları

Key	Value	Amaç
`HeartbeatInterval`	`60`	Saniye cinsinden heartbeat aralığı
`MeterValueSampleInterval`	`30` (admin değiştirilebilir)	MeterValues yayma sıklığı (saniye)
`ConnectionTimeOut`	`30` (admin değiştirilebilir)	Boş bağlantı timeout (saniye)
`WebSocketPingInterval`	`30`	TCP keep-alive ping aralığı (saniye)
`LocalAuthorizeOffline`	`true`	Offline RFID yetkilendirme aktif
`LocalPreAuthorize`	`true`	RFID öncelikli yetkilendirme
`AllowOfflineTxForUnknownId`	`false`	Bilinmeyen RFID offline modda reddedilir
`ResetRetries`	`3`	Reset komutu başarısızsa retry sayısı
`TransactionMessageAttempts`	`3`	Mesaj retry sayısı
`TransactionMessageRetryInterval`	`60`	Retry öncesi bekleme süresi (saniye)

8.2. Desteklenmeyen Anahtarlar

Charger bir anahtar için RejectedNotSupported yanıtı dönerse Zeus bu durumu audit log'a yazar ancak bağlantı veya boot akışını kesmez. Eksik anahtarlar charger'ın özelliği olarak kabul edilir.

9. Vendor-Specific DataTransfer (ZJ-Beny)

OCPP 1.6J DataTransfer mesajı vendor-specific genişletmeler için kullanılır. Zeus, vendorId="ZJ-Beny" ile gelen mesajları tanır ve özel akışla işler.

9.1. Tanınan messageId'ler

messageId	Amaç
`DLBCloud`	Dynamic Load Balancing telemetri (≥10 sn interval)
`DLBStatus`	DLB anlık durumu (mod, current limit, fazlar)
`PVStatus`	PV/solar entegrasyon durumu (üretim, surplus)
`MeterSnapshot`	Ek metering verileri (standart MeterValues dışında)

9.2. Bilinmeyen Mesajlar

Bilinmeyen messageId → Zeus UnknownMessageId döner (akış kesilmez, charger normal işleyişine devam eder).
Bilinmeyen vendorId → Zeus UnknownVendorId döner.

Diğer üretici vendor-specific mesajları için Zeus operasyon ekibiyle iletişime geçin; tanıma kuralları konfigüre edilebilir.

10. Saha Kurulum Akışı (Teknisyen)

Aşağıdaki sıralı checklist Beny BCP-AT2N-P için hazırlanmıştır. Diğer charger'larda adımlar benzer akışı izler.

10.1. Adım Adım Kurulum

Charger'ı AP moduna al:
- Emergency Stop butonuna bas + Test butonu basılı tut + Power-on yap.
- Yeşil LED yanıp sönmeye başlar (AP mode aktif).
Telefon/laptop ile Wi-Fi'ye bağlan:
- SSID: EVSE-xxxx (xxxx charger seri numarasının son 4 hanesi)
- Default password: 12345678
Güvenlik uyarısı: Default Wi-Fi password sahada mutlaka değiştirilmelidir.
Tarayıcıdan AP arayüzünü aç:
- URL: http://192.168.1.1
- Önerilen tarayıcı: Chrome / Edge
Network sekmesinden bağlantı tipini seç:
- Wi-Fi (saha SSID + password)
- Ethernet (DHCP veya statik IP)
- 4G (SIM kart + APN)
OCPP sekmesine geç: Zeus admin UI'dan üretilen kurulum PDF'inde 6 alanı gir:
- Central System Hostname
- Central System Port
- Charge Point Path
- Charge Point Identity (CPID)
- Authorization Username (= CPID)
- Authorization Password
Kaydet:
- Charger otomatik restart eder.
OCPP bağlantı doğrulaması:
- Yeşil pulse LED bekle (≤30 sn).
- Pulse görünürse OCPP bağlandı (BootNotification.Accepted alındı).
Bağlanamadığında:
- Yeşil slow blink ise Zeus admin UI OCPP Audit Log sayfasına gir.
- Charger CPID'sini filtrele, son close code'u oku.
- Bu dokümandaki §6 close code referansından çözümü uygula.

10.2. Saha Doğrulama Kontrol Listesi

Yeşil pulse LED aktif
Zeus admin UI'da charger Online olarak görünüyor
Heartbeat son 90 sn içinde alındı
StatusNotification Available durumunda
Test RFID ile Authorize başarılı

11. Sürüm ve Sözleşme Bilgileri

Bilgi	Değer
OCPP 1.6J Spec	OCA `ocpp-j-1.6-specification.pdf`
python-ocpp library	`>=0.27.0,<2.0.0`
Bu doküman versiyonu	`1.0` (Faz 2 release)
Yayın tarihi	Faz 2 production rollout

11.1. Versiyonlama Politikası

Non-breaking ekler (yeni configuration key, yeni vendor messageId, yeni close code) → minor version artışı.
Breaking değişiklikler (URL format, auth header, CPID regex, mevcut close code anlamı) → major version artışı.
Tüm breaking değişiklikler ayrı OCPP_INTEGRATION_CHANGELOG.md dosyasında listelenir.

11.2. Geriye Dönük Uyumluluk

Mevcut charger filolarını kırmamak için Zeus aşağıdaki kuralları uygular:

Mevcut close code anlamları değişmez.
Mevcut configuration key'lerin default value'ları kaldırılmaz (ancak admin override edebilir).
Yeni vendor messageId eklenirken eskileri deprecate edilmez.

12. SSS / Troubleshooting

"Charger sürekli reconnect ediyor"

Olası neden: BootNotification Rejected dönüyor.

Çözüm:

Zeus admin UI'da charger detay sayfasındaki last_boot_at alanını kontrol et.
BootNotification payload'unda chargePointVendor ve chargePointModel Zeus tarafında tanımlı mı kontrol et.
OCPP version uyuşmazlığı (charger 2.0.1 göndermiş, endpoint 1.6) — endpoint URL'ini düzelt.

"MeterValues görünmüyor"

Olası neden: ConnectionTimeOut çok düşük; charger her interval'da disconnect edip MeterValues göndermeden timeout'a ulaşıyor.

Çözüm:

Zeus admin UI'dan ConnectionTimeOut değerini artır (default 30 → 60 veya 120).
MeterValueSampleInterval çok yüksek olabilir; 30 sn'den fazla ise düşür.
Charger transaction modunda mı kontrol et (MeterValues yalnızca aktif transaction sırasında veya MeterValuesAlignedData ile periyodik gelir).

"Authorize her zaman Invalid dönüyor"

Olası neden: RFID id_tag Zeus DB'sinde kayıtlı değil veya status='Blocked' durumunda.

Çözüm:

ocpp_auth_list_entries tablosunda RFID UID'i ara.
Yoksa Zeus admin UI'dan Auth List sayfasında yeni entry ekle.
Varsa status alanını Accepted olarak güncelle.

"Charger bağlandı ama Zeus 'Offline' gösteriyor"

Olası neden: Heartbeat akışı çalışmıyor.

Çözüm:

Charger'ın HeartbeatInterval configuration değerini 60 olarak set et.
Network'te NAT timeout charger'ın TCP bağlantısını koparmıyor mu kontrol et (WebSocketPingInterval 30 sn olmalı).
Zeus tarafındaki charger heartbeat watchdog logunu incele.

"Reservation reddediliyor"

Olası neden: Connector durumu Available değil veya başka rezervasyon aktif.

Çözüm:

StatusNotification currentStatus alanını kontrol et.
Mevcut rezervasyonu CancelReservation ile temizle.
Connector ID doğru gönderildi mi (1-tabanlı, 0 = whole charger).

Ek Kaynaklar

Zeus Admin UI: OCPP Charger yönetimi Settings → Charging Stations
Audit Log: Settings → OCPP Audit Log
Python-OCPP repo: https://github.com/mobilityhouse/ocpp
OCPP Spec (OCA): https://www.openchargealliance.org/

Belge sahibi: Zeus 2.0 Platform Ekibi

1. Genel Bakış​

Desteklenen Protokol Versiyonları​

Desteklenen Feature Profile'lar (OCPP 1.6J)​

İlk Doğrulanmış Charger​

2. WebSocket Endpoint'leri​

3. Charger-Side Configuration Reference​

3.1. Beny BCP-AT2N-P UI Alanları​

3.2. Nihai Bağlantı URL'i​

3.3. CPID Format Kısıtlaması​

4. Authentication​

4.1. HTTP Basic Auth Header​

4.2. Username = CPID Kuralı​

4.3. Password Yönetimi​

4.4. Rate Limit (Brute-Force Koruması)​

5. Subprotocol Negotiation​

5.1. Önerilen Davranış​

5.2. Header Eksikse (Vendor Compatibility)​

5.3. Yanlış Subprotocol​

6. WebSocket Close Code Reference​

7. Bağlantı LED Sinyalleri (Beny BCP-AT2N-P)​

8. Boot Notification Sonrası Otomatik Konfigürasyon​

8.1. Otomatik Uygulanan Konfigürasyon Anahtarları​

8.2. Desteklenmeyen Anahtarlar​

9. Vendor-Specific DataTransfer (ZJ-Beny)​

9.1. Tanınan messageId'ler​

9.2. Bilinmeyen Mesajlar​

10. Saha Kurulum Akışı (Teknisyen)​

10.1. Adım Adım Kurulum​

10.2. Saha Doğrulama Kontrol Listesi​

11. Sürüm ve Sözleşme Bilgileri​

11.1. Versiyonlama Politikası​

11.2. Geriye Dönük Uyumluluk​

12. SSS / Troubleshooting​

"Charger sürekli reconnect ediyor"​

"MeterValues görünmüyor"​

"Authorize her zaman Invalid dönüyor"​

"Charger bağlandı ama Zeus 'Offline' gösteriyor"​

"Reservation reddediliyor"​

Ek Kaynaklar​

1. Genel Bakış

Desteklenen Protokol Versiyonları

Desteklenen Feature Profile'lar (OCPP 1.6J)

İlk Doğrulanmış Charger

2. WebSocket Endpoint'leri

3. Charger-Side Configuration Reference

3.1. Beny BCP-AT2N-P UI Alanları

3.2. Nihai Bağlantı URL'i

3.3. CPID Format Kısıtlaması

4. Authentication

4.1. HTTP Basic Auth Header

4.2. Username = CPID Kuralı

4.3. Password Yönetimi

4.4. Rate Limit (Brute-Force Koruması)

5. Subprotocol Negotiation

5.1. Önerilen Davranış

5.2. Header Eksikse (Vendor Compatibility)

5.3. Yanlış Subprotocol

6. WebSocket Close Code Reference

7. Bağlantı LED Sinyalleri (Beny BCP-AT2N-P)

8. Boot Notification Sonrası Otomatik Konfigürasyon

8.1. Otomatik Uygulanan Konfigürasyon Anahtarları

8.2. Desteklenmeyen Anahtarlar

9. Vendor-Specific DataTransfer (ZJ-Beny)

9.1. Tanınan messageId'ler

9.2. Bilinmeyen Mesajlar

10. Saha Kurulum Akışı (Teknisyen)

10.1. Adım Adım Kurulum

10.2. Saha Doğrulama Kontrol Listesi

11. Sürüm ve Sözleşme Bilgileri

11.1. Versiyonlama Politikası

11.2. Geriye Dönük Uyumluluk

12. SSS / Troubleshooting

"Charger sürekli reconnect ediyor"

"MeterValues görünmüyor"

"Authorize her zaman Invalid dönüyor"

"Charger bağlandı ama Zeus 'Offline' gösteriyor"

"Reservation reddediliyor"

Ek Kaynaklar