Web Master — Integration in Betrieb nehmen

Zweck der Integration

Web Master liest den Zustand der Zentrale und der Leuchten über die lokale HTTP-API des EZ2-Adapters, Schema ges-v2. Diese Schnittstelle dient der Überwachung. Das Starten von Tests wird unter Modbus IP beschrieben.

Verbindung vorbereiten

1. Zentrale und Integrationsrechner mit einem Netzwerk verbinden, in dem sie miteinander kommunizieren können.
2. IP-Adresse der Zentrale notieren. Eine feste Adresse oder DHCP-Reservierung vorsehen.
3. In den Einstellungen der lokalen API die Bereitstellung von Leuchtendaten aktivieren. Andernfalls liefern Leuchtenliste und Einzeldiagnose HTTP 403.
4. Die Adresse der Zentrale im Browser öffnen. Danach /data/systeminfo.php und /lumlist.php prüfen.
5. Im Web Master die EZ2-Integration wählen und die Adresse der Zentrale entsprechend der Web-Master-Konfiguration eintragen.
6. Die Liste importieren, Geräteanzahl und Standorte mit der Zentrale vergleichen. Fehlerbeschreibungen aus /data/errorcodes.php in das Wörterbuch übernehmen.

192.168.1.50 ist nur eine Beispieladresse. Die Dienste gehören in ein vertrauenswürdiges Überwachungsnetz. Diese lokale Schnittstelle benötigt keinen Token; sie darf nicht direkt aus dem Internet erreichbar sein.

Abgerufene Daten

Vollständige Beispiele und HTTP-Fehlerbehandlung: EZF API.

Geräte eindeutig identifizieren

Die Leuchten-ID ist Kanal × 65536 + physische Adresse. Kanäle: 1 = BUS1, 2 = BUS2, 3 = AirBus. Die physische Adresse 10 ergibt 65546, 131082 beziehungsweise 196618. Das Feld adresse vollständig speichern und nicht auf 16 Bit begrenzen.

Nach einem Wechsel von einer älteren Integration mit reinen physischen Adressen den Bestand neu synchronisieren. Alte Datensätze nach dem Verfahren des Web Masters entfernen, damit keine Duplikate entstehen. Ein Kanalwechsel ändert die ID.

Spalten der Leuchtenliste

Leere Felder weder durch null noch durch das aktuelle Datum ersetzen. Die eingestellte Autonomiezeit ist kein gemessenes Ergebnis des letzten Tests. Bei NVG wird die Schaltungsart nur angegeben, wenn beide Ausgänge übereinstimmen. Bei Kommunikationsverlust bleiben Schaltungsart und Betriebszeit leer.

Prüfung vor der Abnahme

• Anzahl und IDs stimmen mit der Zentrale überein.
• Dieselbe physische Adresse auf BUS1, BUS2 und AirBus ergibt drei unterschiedliche Geräte.
• Gerätetyp und Standort sind erkennbar; Fxxx-Codes besitzen verständliche Beschreibungen.
• Simulierte LED-, Akku- und Kommunikationsfehler werden korrekt angezeigt.
• Fehlende HTTP-Antworten werden als fehlende aktuelle Daten dargestellt.
• Test, Sperre und Suche werden vom Zustand einer fehlerfreien Anlage unterschieden.

Der lokale Simulator unterstützt die Vorbereitung. Zur Abnahme gehören eine reale Zentrale und der vorgesehene Web Master. Siehe Programme und Downloads.

Modbus IP — Konfiguration und Zustände auslesen

Verbindungsparameter

Die EZF-Zentrale ist Modbus-TCP-Server; GLT/BMS oder Tester sind Clients. Diese Beschreibung gilt für Registertabelle v1 ab Firmware 10.38.

Eine Verbindung ohne Datenverkehr kann nach 3 Sekunden geschlossen werden. Der Client muss sie erneut öffnen können. Modbus besitzt keine Authentifizierung; den Zugriff auf ein vertrauenswürdiges Überwachungsnetz begrenzen.

In der Zentrale aktivieren

1. Einstellungen → Externe Kommunikation öffnen und Modbus TCP aktivieren. Entsprechende Berechtigungen sind erforderlich; die genaue Menübezeichnung hängt von der Bildschirmversion ab.
2. Bei Konfiguration über die lokale Webseite das Speichern mit der Service-PIN bestätigen.
3. Den geplanten Neustart und die erneute Erreichbarkeit abwarten.
4. Im Tester IP-Adresse, Port 502 und die zum Client passende Unit ID eintragen.
5. Identität lesen: Register 0 muss 0x455A, Register 1 die Version der Registertabelle 1 liefern.
6. Leuchtenliste lesen und vergleichen. Für reine Überwachung keine Ferntests aktivieren.

TCP, RTU und die Freigabe von Ferntests sind standardmäßig ausgeschaltet. In Leuchtenergebnissen bezeichnet TCP auch den Betriebsdauertest; dies ist vom Netzwerktransport Modbus TCP zu unterscheiden.

Erste Lesezugriffe

Register 0x0002: Bit 0 Störung, 1 Kommunikationsfehler, 2 Sperre, 3 Suche, 4 Initialisierung/Konfiguration, 5 FRAM-Speicherfehler. Register 0 nicht als 40001 eingeben, außer der Client rechnet die 4xxxx-Notation ausdrücklich in eine nullbasierte Adresse um.

Leuchtenregister

BUS1 beginnt bei 0x1000 (200 Slots), BUS2 bei 0x3000 (200), AirBus bei 0x5000 (500). Ein Slot umfasst 16 Wörter. Adresse von Slot i, ab 1 gezählt: Basis + 16 × (i−1). Der Slot ist eine Listenposition, nicht die physische Leuchtenadresse. Ein leerer Slot enthält ausschließlich null.

0xFFFF im Ergebnis bedeutet unbekannt, veraltet oder drahtgebundene Leuchte — kein positives Ergebnis. Bei gemeldetem FRAM-Fehler können Zustände unbestätigt sein, obwohl eine Liste lesbar ist. Ein aktueller Lesezugriff ersetzt keinen archivierten Prüfbericht.

AirBus-Test aus der Ferne

Zuerst lesen. Danach Ferntests lokal freigeben und im Tester Schreibzugriff, Seriennummer sowie den einzelnen Befehl bestätigen. Diese Registertabelle unterstützt die Steuerung von AirBus-Leuchten und -Gruppen. BUS1/BUS2 dienen der Überwachung; ein Teststart für drahtgebundene Leuchten liefert Ausnahme 01.

FC16 schreibt ab 0x0100 genau sieben Wörter:

Beispiel: TF für AirBus 42, UID=196650, Auftrag 1: 0000 0001 0001 0000 0003 002A A55A.

UID = Kanal × 65536 + Adresse. Vor dem Senden die aktuelle UID prüfen. Ein gemeinsames übergeordnetes System sollte Auftrags-IDs für beide Transportwege vergeben. Eine identische ID mit identischem Befehl startet keinen zweiten Test; veränderter Inhalt mit derselben ID ist ein Fehler.

Nach Annahme von FC16 0x0100–0x0107 lesen. Zustand 1 = Warteschlange, 2 = angenommen/läuft, 3 = Ergebnisse gesammelt, 4 = abgelehnt, 5 = STOP angenommen. Zustand 3 bedeutet nicht, dass alle Leuchten bestanden haben. Leuchtenergebnisse und Gruppenzähler auswerten. Zustand 5 bestätigt nicht den Empfang von STOP durch jede Leuchte. Nach einem Neustart Startkennung und aktuellen Zustand lesen; alte Befehle nicht automatisch erneut ausführen.

Fehler und Diagnose

Bei Verbindungsproblemen IP, Port, TCP-Freigabe, Neustart, Firewall und Clientlimit prüfen. TX/RX-Telegramme und JSON-/CSV-Export im Tester sichern.

Optional: Modbus RTU

RTU verwendet dieselbe Registertabelle: 19200 Bit/s, 8E1, Adresse 1–247, standardmäßig 1. Dafür ist ein freier BUS1 oder BUS2 ohne gespeicherte Leuchten erforderlich. Modbus RTU und EZF-Leuchtenprotokoll nicht auf demselben Port mischen. Broadcast-Adresse 0 führt keine Befehle aus.

Siehe Windows-/macOS-Tester und lokale Übung.

EZF API — JSON, TSV und Fehlerbehandlung

Geltungsbereich

Diese Anleitung beschreibt die lokale Web-Master-/EZ2-Schnittstelle, Schema ges-v2. Vier GET-Anfragen sind ausschließlich lesend. Zum Starten von Tests Modbus IP verwenden. 192.168.1.50 ist eine Beispieladresse.

Systemzustand als JSON

macOS / Linux:

curl --fail --max-time 10 http://192.168.1.50/data/systeminfo.php

Windows PowerShell:

Invoke-RestMethod -Uri "http://192.168.1.50/data/systeminfo.php" -TimeoutSec 10

Ausgewählte Antwortfelder für eine Leuchte ohne Fehler:

{
  "systemtype": "EZ2",
  "status_codes": ["0001"],
  "error_codes": ["0000"],
  "mapping_complete": true,
  "luminaire_count": 1,
  "communication_error_count": 0,
  "fault_count": 0,
  "error_schema": "ges-v2",
  "address_schema": "channel16-address16-decimal",
  "optional_unavailable": ["letzte_testdauer", "aktualisiert_am"]
}

Dieses Beispiel zeigt das Format. Tatsächliche Werte hängen von der Anlage ab. Die Antwort enthält außerdem NVG-Zähler, Fehlerwörterbuch und Statusumfang. mapping_complete=true bestätigt nicht die Verfügbarkeit optionaler Messwerte oder Zeitangaben.

Mehrere Flags können gleichzeitig gelten. Immer gemeinsam mit error_codes auswerten. Eine Anlage ohne konfigurierte Leuchten ist gestört beziehungsweise unbestätigt.

TSV-Liste

curl --fail --max-time 10 http://192.168.1.50/lumlist.php -o oprawy.tsv

Windows PowerShell:

Invoke-WebRequest -Uri "http://192.168.1.50/lumlist.php" -OutFile "oprawy.tsv" -TimeoutSec 10
$oprawy = Import-Csv -Path "oprawy.tsv" -Delimiter "`t"
$oprawy | Format-Table adresse, geraetetyp, fehlercode, ortstext

Beispiel: Tabulatoren trennen die Spalten; leere Spalten bleiben erhalten.

adresse geraetetyp  gruppe  ueberwachung    schaltungsart   betriebszeit    letzte_testdauer    fehlercode  ortstext    aktualisiert_am
196618  AW  0   1   DS  LTM_3H      0000    Flur    

Kopfzeile und Datensätze haben jeweils zehn Felder. Nicht nach beliebigen Leerzeichen aufteilen, sonst gehen leere Felder verloren. Die Web-Master-Anleitung erklärt die Spalten. ueberwachung=0 ist nicht gleichbedeutend mit Kommunikationsverlust.

Einzelne Leuchte diagnostizieren

Die ID aus der ersten TSV-Spalte verwenden:

curl --fail --max-time 10 "http://192.168.1.50/data/luminaire.php?id=196618"

Beispiel für eine normale AirBus-Leuchte mit Adresse 10:

{"id":196618,"channel":3,"physical_address":10,"error_code":"0000","nvg":null}

Bei NVG enthält nvg die Felder led1, led2, mains, input_l1, input_l2, maintained1, maintained2 und communication_error. LED-Werte: 0 aus, 1 an, 2 blinkend, 3 Fehler. Bei communication_error=true sind die übrigen NVG-Werte der zuletzt empfangene Zustand und keine Bestätigung des aktuellen Zustands.

Fehlerwörterbuch

curl --fail --max-time 10 http://192.168.1.50/data/errorcodes.php

Codes als vierstellige HEX-Zeichenfolgen einschließlich führender Nullen erhalten.

Fxxx sind Codes des EZF-Adapters. Beschreibungen in das Integrationssystem übernehmen. Ein einzelner Leuchtencode beschreibt nicht alle gleichzeitigen Fehler; zusätzliche NVG-Diagnose auswerten.

Antworten und Aktualisierung

Timeout und begrenzte Wiederholungen mit Verzögerung vorsehen. Das Abfrageintervall bei der Inbetriebnahme festlegen. Keine unbeschränkte Abfrageschleife verwenden. Fehler, leere Antworten und alte Zustände niemals als aktuelles OK darstellen.

Die TSV-Liste ist in dieser Version auf 24576 Bytes begrenzt. Bei Überschreitung wird HTTP 503 statt einer abgeschnittenen Liste mit HTTP 200 geliefert. Getrennte Endpunktabfragen bilden keinen atomaren Gesamtbericht.

Integration prüfen

Erfolgreiches Lesen, deaktivierte Leuchten-API, ungültige und nicht vorhandene IDs sowie Verbindungsverlust prüfen. Die Fehlerdarstellung mit dem Display der Zentrale vergleichen. Werkzeuge und Simulatoren ermöglichen die Vorbereitung ohne angeschlossene Zentrale.

Integrationswerkzeuge — Windows, macOS und Simulatoren

Downloads

Die Dateien stehen direkt in der Wiki bereit. Ein GitHub-Konto ist nicht erforderlich.

Auf dem Mac unter Apple-Menü → Über diesen Mac prüfen: Apple M… = Apple Silicon; Intel-Prozessor = Intel-Paket. Der Tester installiert keine Firmware.

Modbus-Tester starten

1. Das gesamte ZIP herunterladen und entpacken.
2. Windows: EZF-Modbus-Tester.exe aus dem entpackten Verzeichnis starten; Begleitdateien beibehalten.
3. macOS: EZF-Modbus-Tester.app aus dem passenden Paket öffnen.
4. PL, DE oder EN wählen.
5. Auf dem Mac den Zugriff auf das lokale Netzwerk erlauben, wenn das System danach fragt.

Version 1.0.2 ist weder mit Developer ID signiert noch notarisiert. Falls macOS sie blockiert, die Freigabe dieser einzelnen Anwendung unter Datenschutz und Sicherheit prüfen. Keine systemweiten Schutzfunktionen deaktivieren. BUILD.txt nennt die kompilierte Architektur.

Ohne Zentrale üben

1. Den eingebauten lokalen Simulator im Tester starten.
2. Host 127.0.0.1, Port 1502 einstellen.
3. Identität lesen. Erwartete Simulator-Seriennummer: EZFDEMO0001.
4. BUS1-, BUS2- und AirBus-Liste lesen; UID, Zustände und NVG ansehen.
5. TX/RX-Telegramme sowie JSON-/CSV-Export prüfen.
6. Für Befehlsübungen Schreibzugriff erlauben und die Simulator-Seriennummer bestätigen.
7. TF starten, Auftrag und Ergebnisse beobachten; STOP prüfen.

Der Simulator bildet Kommunikation und Beispielantworten ab. Er prüft weder physische Busleitungen noch Funk oder Akkukapazität.

Reale Zentrale verbinden

Simulator stoppen oder trennen, IP-Adresse der Zentrale und Port 502 eintragen. Mit Seriennummer und Listenvergleich beginnen. Ferntests erfordern eine eigene Freigabe in der Zentrale und die Bestätigung jedes Befehls im Tester. Steuerbefehle werden nicht automatisch wiederholt.

API-Tester und REST-Simulator

API-Paket entpacken. Es enthält den HTML-Tester und fertige Simulatoren für Windows und beide Mac-Architekturen. Die ursprüngliche Startdatei README_KLIENT_PL.html ist polnisch; die vollständigen Startschritte stehen hier auf Deutsch: 1. Windows: Windows/EZF_API_Simulator.exe starten. Mac: App aus macOS-AppleSilicon oder macOS-Intel öffnen. 2. http://127.0.0.1:8765/ öffnen, Szenario und Seriennummer wählen und übernehmen. 3. API-Tester öffnen, danach API prüfen wählen. Der vorhandene API-Tester und REST-Simulator haben eine deutsche Oberfläche. 4. Systemzustand, TSV-Liste, Fehlerwörterbuch und einzelne Leuchte prüfen. 5. Für die reale Zentrale deren Adresse als API-Basis eintragen und erneut lesen.

Alternativ Webmaster_API_Tester_DE.html öffnen. Bei Einschränkungen lokaler Dateien den vom Simulator über HTTP bereitgestellten Tester verwenden oder die curl-/PowerShell-Beispiele aus EZF API nutzen. Keine globalen Browserschutzfunktionen deaktivieren. Das Schließen des Browsers beendet den Simulator nicht; Simulator beenden verwenden. Die Programme sind nicht signiert/notarisiert. serial_number und simulator=true sind Simulatorzusätze, keine Felder der realen Zentrale.

Schulung am Zentralendisplay

Die Zentralensimulatoren enthalten EZF 10.107 klassisch, METRO 10.109 und den R6-Vergleich. Sie dienen der Bedienerschulung und stellen keinen Modbus- oder REST-Server bereit.

Angaben bei Problemen

Version von Zentrale und Tester, Betriebssystem, Ereigniszeit, HTTP-/Modbus-Meldung sowie Telegramme oder Export beifügen. Passwörter und Zugangsdaten entfernen. Angeben, ob der Fehler im Simulator, an der realen Zentrale oder im vorgesehenen Web Master auftritt.