Web Master — uruchomienie integracji

Do czego służy integracja

Web Master odczytuje stan centrali i opraw przez lokalne HTTP API zgodne z adapterem EZ2, schemat ges-v2. Interfejs udostępnia dane do nadzoru. Uruchamianie testów opisuje osobno Modbus IP.

Przygotuj połączenie

1. Podłącz centralę i komputer integratora do sieci, w której mogą się komunikować.
2. Zanotuj adres IP centrali. Zapewnij stały adres lub rezerwację DHCP.
3. W ustawieniach lokalnego API centrali włącz udostępnianie danych opraw. Wyłączona opcja powoduje HTTP 403 dla listy i diagnostyki opraw.
4. Otwórz adres centrali w przeglądarce. Następnie sprawdź /data/systeminfo.php i /lumlist.php.
5. W Web Master wybierz integrację EZ2 i wprowadź adres centrali, zgodnie z konfiguracją Twojego Web Mastera.
6. Zaimportuj listę, porównaj liczbę urządzeń i lokalizacje z centralą. Dodaj opisy kodów błędów według /data/errorcodes.php.

Adres 192.168.1.50 w przykładach zastąp adresem swojej centrali. Usługi udostępniaj w zaufanej sieci nadzorczej. Ten interfejs lokalny nie wymaga tokenu; nie wystawiaj go bezpośrednio do Internetu.

Jakie dane pobiera Web Master

Pełne przykłady i obsługę HTTP znajdziesz w API — odczyt danych.

Identyfikacja urządzeń

ID oprawy wylicza się jako kanał × 65536 + adres fizyczny. Kanały: 1 = BUS1, 2 = BUS2, 3 = AirBus. Fizyczny adres 10 daje odpowiednio 65546, 131082 i 196618. Pole adresse zapisuj w całości; nie ograniczaj go do 16 bitów.

Po przejściu ze starszej integracji używającej samych adresów fizycznych wykonaj ponowną synchronizację inwentarza. Usuń stare rekordy zgodnie z procedurą Web Mastera, aby uniknąć zdublowanych opraw. Przeniesienie oprawy do innego kanału zmienia jej ID.

Kolumny listy opraw

Nie zastępuj pustych pól zerem ani aktualną datą. Ustawiony czas autonomii nie jest pomiarem czasu ostatniego testu. Dla NVG tryb jest podawany tylko wtedy, gdy oba wyjścia mają ten sam tryb; przy utracie komunikacji tryb i autonomia pozostają puste.

Sprawdzenie przed odbiorem

• Liczba i ID opraw zgadzają się z centralą.
• Ten sam adres na BUS1, BUS2 i AirBus tworzy trzy różne rekordy.
• Typ i lokalizacja są rozpoznawane, a kody Fxxx mają czytelne opisy.
• Zasymulowana awaria LED, baterii i komunikacji jest poprawnie prezentowana.
• Brak odpowiedzi HTTP jest pokazywany jako brak aktualnych danych.
• Stany testu, blokady i wyszukiwania są odróżniane od sprawności instalacji.

Lokalny symulator pomaga sprawdzić integrację. Odbiór wymaga próby na rzeczywistej centrali i docelowym Web Masterze. Zobacz programy i materiały do pobrania.

Modbus IP — konfiguracja i odczyt statusów

Parametry połączenia

Centrala EZF jest serwerem Modbus TCP; BMS lub tester jest klientem. Opis dotyczy mapy v1, dostępnej od firmware 10.38.

Połączenie bez ruchu może zostać zamknięte po 3 sekundach; klient powinien umieć ponownie je otworzyć. Modbus nie ma uwierzytelniania — dostęp ogranicz do zaufanej sieci nadzorczej.

Włączenie w centrali

1. Otwórz Ustawienia → Komunikacja zewnętrzna i włącz Modbus TCP. Dostęp wymaga odpowiednich uprawnień.
2. Przy konfiguracji przez lokalną stronę WWW potwierdź zapis PIN-em serwisowym.
3. Poczekaj na zaplanowany restart i powrót centrali.
4. Uruchom tester, wpisz IP, port 502 i Unit ID zgodny z konfiguracją klienta.
5. Odczytaj tożsamość. Rejestr 0 powinien mieć wartość 0x455A, a rejestr 1 — wersję mapy 1.
6. Pobierz listę opraw i porównaj ją z centralą. Do samego nadzoru nie włączaj zdalnych testów.

TCP, RTU i zezwolenie na zdalne testy są domyślnie wyłączone. Skrót TCP używany przy wyniku oprawy oznacza także test czasu pracy/autonomii; kontekst odróżnia go od transportu Modbus TCP.

Pierwsze odczyty

Flagi rejestru 0x0002: bit 0 awaria, 1 błąd komunikacji, 2 blokada, 3 wyszukiwanie, 4 inicjalizacja/konfiguracja, 5 błąd pamięci FRAM. Rejestru 0 nie wpisuj jako 40001, chyba że używany klient świadomie przelicza notację 4xxxx na adres zerowy.

Mapa opraw

BUS1 zaczyna się od 0x1000 (200 slotów), BUS2 od 0x3000 (200), AirBus od 0x5000 (500). Każdy slot zajmuje 16 słów. Adres slotu i, liczonego od 1, to baza + 16 × (i−1). Slot jest pozycją na liście, a nie fizycznym adresem oprawy. Pusty slot ma wszystkie słowa zerowe.

W polu wyniku 0xFFFF oznacza stan nieznany, nieaktualny lub oprawę przewodową — nie wynik pozytywny. Przy zgłoszonym błędzie FRAM część statusów może być niepotwierdzona mimo odczytywalnej listy. Bieżący odczyt nie zastępuje archiwalnego raportu.

Zdalny test AirBus

Najpierw wykonaj odczyty. Następnie lokalnie zezwól na zdalne testy, a w testerze zaakceptuj zapis, potwierdź numer seryjny i wybrane polecenie. W tej mapie sterowanie dotyczy opraw i grup AirBus; BUS1/BUS2 udostępniają nadzór. Próba startu testu przewodowego zwraca wyjątek 01.

FC16 zapisuje od 0x0100 dokładnie siedem słów:

Przykład TF dla AirBus 42, UID=196650, zadanie 1: 0000 0001 0001 0000 0003 002A A55A.

UID ma wzór kanał × 65536 + adres. Przed wysłaniem sprawdź aktualny UID. Wspólny system nadrzędny powinien nadawać ID zadań dla obu transportów. Identyczne ID i polecenie nie uruchamiają drugiego testu; zmiana treści przy tym samym ID jest błędem.

Po przyjęciu FC16 czytaj 0x0100–0x0107. Stan 1 = kolejka, 2 = przyjęte/trwa, 3 = zebrano wyniki, 4 = odrzucone, 5 = przyjęto STOP. Stan 3 nie oznacza, że wszystkie oprawy przeszły test. Sprawdź wyniki opraw i liczniki grup. Stan 5 nie dowodzi odbioru STOP przez każdą oprawę. Po restarcie odczytaj identyfikator uruchomienia i bieżący stan; nie odtwarzaj automatycznie starego polecenia.

Błędy i diagnostyka

Przy braku połączenia sprawdź IP, port, włączenie TCP, restart, firewall i limit klientów. W testerze zapisz telegramy TX/RX oraz eksport JSON/CSV.

Opcjonalnie: Modbus RTU

RTU używa tej samej mapy: 19200 bit/s, 8E1, adres 1–247 (domyślnie 1). Wymaga wolnego BUS1 albo BUS2 bez zapisanych opraw. Nie łącz Modbus RTU i protokołu opraw EZF na tym samym porcie. Adres rozgłoszeniowy 0 nie wykonuje poleceń.

Zobacz testery Windows/macOS i ćwiczenie lokalne.

API EZF — JSON, TSV i obsługa błędów

Zakres

Opis dotyczy lokalnego interfejsu Web Master/EZ2, schemat ges-v2. Cztery żądania GET służą wyłącznie do odczytu. Do sterowania testami użyj Modbus IP. W przykładach 192.168.1.50 jest przykładowym adresem centrali.

Stan systemu w 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

Przykład wybranych pól odpowiedzi dla jednej oprawy bez błędów:

{
  "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"]
}

To fragment ilustrujący format; wartości na instalacji zależą od jej stanu. Odpowiedź zawiera też liczniki NVG, słownik błędów i zakres statusów. mapping_complete=true nie oznacza, że dostępne są opcjonalne pomiary i daty.

Flagi mogą występować równocześnie. Oceniaj je wraz z error_codes. Brak skonfigurowanych opraw jest stanem awaryjnym/niepotwierdzonym.

Lista TSV

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

Przykład (kolumny oddzielają tabulatory; puste kolumny należy zachować):

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

Nagłówek i każdy rekord mają dziesięć pól. Nie dziel wiersza po dowolnych białych znakach: zgubisz puste pola. Znaczenie kolumn opisuje Web Master. Nie myl ueberwachung=0 z brakiem komunikacji.

Diagnostyka pojedynczej oprawy

Weź ID z pierwszej kolumny TSV:

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

Przykładowa zwykła oprawa AirBus 10:

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

Dla NVG pole nvg zawiera led1, led2, mains, input_l1, input_l2, maintained1, maintained2 i communication_error. LED: 0 wyłączony, 1 włączony, 2 migający, 3 awaria. Przy communication_error=true pozostałe wartości NVG są ostatnim odebranym stanem i nie potwierdzają stanu bieżącego.

Słownik błędów

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

Kody zachowuj jako czteroznakowe ciągi HEX, łącznie z zerami z przodu.

Kody Fxxx są kodami adaptera EZF. Dodaj ich opisy do systemu integratora. Jeden kod oprawy nie opisuje wszystkich równoczesnych usterek; wykorzystaj także szczegóły NVG.

Obsługa odpowiedzi i odświeżanie

Klient powinien mieć timeout i ograniczone ponawianie z opóźnieniem. Częstotliwość odczytu dobierz podczas uruchomienia instalacji. Nie uruchamiaj nieograniczonej pętli zapytań. Nie zamieniaj błędu, pustej odpowiedzi ani ostatniego zapamiętanego stanu na aktualny wynik OK.

Lista TSV ma limit 24576 bajtów w opisanym wydaniu. Przekroczenie limitu daje HTTP 503, a nie poprawną odpowiedź z uciętą listą. Odczyty różnych endpointów nie są jednym atomowym raportem.

Próba integracyjna

Sprawdź poprawny odczyt, wyłączone API opraw, błędne i nieistniejące ID oraz utratę połączenia. Porównaj interpretację usterek z ekranem centrali. Narzędzia i symulatory pozwalają przygotować klienta bez podłączonego urządzenia.

Narzędzia integracyjne — Windows, macOS i symulatory

Pobieranie

Pliki są udostępnione bezpośrednio w Wiki; konto GitHub nie jest potrzebne.

Na Macu sprawdź  → Ten Mac: układ Apple M… oznacza Apple Silicon, procesor Intel — paczkę Intel. Tester nie instaluje firmware.

Pierwsze uruchomienie testera Modbus

1. Pobierz i rozpakuj cały ZIP.
2. Windows: uruchom EZF-Modbus-Tester.exe z rozpakowanego katalogu, zachowując pliki towarzyszące.
3. macOS: otwórz EZF-Modbus-Tester.app z właściwej paczki.
4. Wybierz PL, DE lub EN.
5. Na Macu zezwól na dostęp do sieci lokalnej, gdy system o niego poprosi.

Wydanie 1.0.2 nie ma podpisu Developer ID ani notaryzacji. Jeśli macOS je blokuje, zezwolenie dla tej konkretnej aplikacji można sprawdzić w ustawieniach Prywatność i ochrona. Nie wyłączaj zabezpieczeń całego systemu. Plik BUILD.txt podaje architekturę kompilacji.

Ćwiczenie bez centrali

1. W testerze uruchom wbudowany lokalny symulator.
2. Ustaw host 127.0.0.1, port 1502.
3. Odczytaj tożsamość. Oczekiwany numer seryjny symulatora: EZFDEMO0001.
4. Pobierz listę BUS1, BUS2 i AirBus, obejrzyj UID, statusy i NVG.
5. Sprawdź telegramy TX/RX, eksport JSON i CSV.
6. Do ćwiczenia poleceń zaakceptuj zapis i potwierdź numer seryjny symulatora.
7. Uruchom TF, obserwuj zadanie i wyniki; sprawdź STOP.

Symulator modeluje komunikację i przykładowe odpowiedzi. Nie bada fizycznej magistrali, radia ani pojemności akumulatora.

Połączenie z rzeczywistą centralą

Zatrzymaj lub odłącz symulator, wpisz IP centrali i port 502. Zacznij od odczytu numeru seryjnego i porównania listy opraw. Zdalne testy wymagają oddzielnego zezwolenia w centrali i każdorazowego potwierdzenia w aplikacji. Tester nie ponawia automatycznie poleceń sterujących.

Tester API i symulator REST

Rozpakuj pakiet klienta API. Zawiera tester HTML oraz gotowe symulatory dla Windows i Maca; dobierz architekturę Maca. Zacznij od pliku README_KLIENT_PL.html w paczce. 1. Uruchom właściwy symulator REST zgodnie z dołączoną instrukcją i sprawdź wyświetlony adres lokalny. 2. Otwórz tester HTML i wpisz ten adres jako bazę API. 3. Sprawdź stan systemu, listę TSV, słownik błędów i dane pojedynczej oprawy. 4. Następnie powtórz odczyty z adresem prawdziwej centrali.

Jeśli przeglądarka ogranicza dostęp strony do sieci lokalnej, użyj instrukcji dołączonej do testera lub przykładów curl/PowerShell z API EZF. Nie zmieniaj globalnych zabezpieczeń przeglądarki.

Materiały szkoleniowe centrali

Symulatory centrali zawierają widok klasyczny EZF 10.107, METRO 10.109 i porównanie R6. Służą do nauki obsługi ekranu; nie są serwerem Modbus ani REST.

Dane do zgłoszenia problemu

Dołącz wersję centrali i testera, używany system operacyjny, czas zdarzenia, komunikat HTTP/Modbus i telegramy lub eksport. Usuń hasła i dane dostępowe. Opisz, czy problem występuje w symulatorze, na rzeczywistej centrali czy w docelowym Web Masterze.