AMAGE PVD

Zasada działania

PVD może działać jako aplikacja terminalowa, jednak głównym założeniem jest praca ciągła, w charakterze usługi systemowej. Aplikacja ładuje i rejestruje moduły wtyczek wejściowych oraz wyjściowych. Kiedy wtyczka wejściowa generuje wiadomość, przekazuje ją do rdzenia aplikacji, a ta rozsyła ją do poszczególnych wtyczek wyjściowych. Aplikacja uruchamiana jest zarówno na urządzeniach embedded, jak i na komputerach klasy serwerowej. Może pracować w systemie Linux oraz Windows.

Wtyczki wejściowe i wyjściowe

Dopuszczalne są różne implementacje wtyczek wejściowych i wyjściowych. Wtyczka wejściowa odpowiada nie tylko za zebranie danych, ale też za utworzenie zalążka wiadomości w postaci mapowań UUID celu (standardowo ustawienie parametru zasobu w systemie Amage) na zebrane wartości. Następnie wtyczka przekazuje tak utworzoną wiadomość do rdzenia aplikacji PVD, który zajmuje się dalszym jej przetwarzaniem. Wtyczka wyjściowa odpowiada za obsługę wiadomości. Standardowo dostępną wtyczką wyjściową jest moduł odpowiadający za przekazywanie danych do sparowanego serwera Amage Software Suite.

Wymagania

Jedynym bezwzględnym wymaganiem PVD jest dostępność środowiska uruchomieniowego Java w wersji 21 lub nowszej oraz ilość pamięci pozwalająca na buforowanie danych w przypadku problemów ze swobodnym przekazywaniem wiadomości wtyczkom wyjściowym - zalecane jest minimum 512 MB RAM.

Instalacja i konfiguracja aplikacji

Instalacja aplikacji polega na rozpakowaniu archiwum pvd-all.zip w wybranej lokalizacji. W następnej kolejności należy skonfigurować aplikację oraz jej moduły, co opisane zostało w tym rozdziale. Pliki konfiguracyjne znajdują się w katalogu configs i podkatalogach, wszystkie pliki konfiguracyjne są zapisywane w formacie JSON. Jakakolwiek modyfikacja konfiguracji aplikacji wymaga jej restartu - tylko wtedy wprowadzone zmiany odniosą skutek.

Alternatywne metody instalacji np. z plików DEB oraz uruchamiania aplikacji opisane zostały w rozdziale "Instalacja i uruchamianie aplikacji".

Ustawienie katalogu startowego

Aplikacja w trakcie uruchamiania korzysta ze zmiennej systemowej user.home w celu określenia katalogu startowego zawierającego wszystkie dane konfiguracyjne oraz jako miejsce przechowywania danych dodatkowych (baza danych na dane tymczasowe, logi itp.).

Domyślnie katalog ten jest ustawiany na katalog użytkownika. Aby uruchomić aplikację z innym katalogiem startowym, należy uruchomić maszynę JVM z opcją

-Duser.home = <katalog>. Pozwoli to wskazać dowolne miejsce przechowywania plików.

Struktura katalogu: * configs - katalog z konfiguracjami aplikacji * inputs - katalog z bibliotekami wtyczek wejściowych * outputs - katalog z bibliotekami wtyczek wyjściowych * db - katalog lokalnej bazy danych * logs - katalog na logi aplikacji oraz wszystkich wtyczek wejściowych/wyjściowych

Wszystkie ścieżki w dokumentacji odnoszą się względem katalogu user.home. Dla ułatwienia w ścieżkach wszystkich danych ten katalog będzie oznaczony jako <user.home>.

Konfiguracja aplikacji

Ścieżka do pliku: <user.home>/configs/core-config.json Plik jest opcjonalny, jeżeli nie istnieje (stan domyślny), aplikacja zostanie uruchomiona z ustawieniami domyślnymi (opisane poniżej).

Przykładowa konfiguracja aplikacji:

 {
    "inputsPath":"file:///path/to/inputs",
    "outputsPath":"file:///path/to/outputs",
    "port":9900,
    "manualNativeLibs":false,
    "debug":false,
    "noRepeat":false,
    "heartbeatTime":-1,
    "cleanupTime": 3600,
    "validityTime": 43200,
    "updateMappingsTime":-1,
    "inputDirs": [ "path1", "path2"],
    "inputEnabled": [ "input-example"],
    "outputDirs": [ "path1", "path2"],
    "outputEnabled": [ "output-example"]
 }

inputPath - (URL) ścieżka do katalogu z modułami wtyczek wejściowych, domyślnie katalog inputs
outputPath - (URL) ścieżka do katalogu z modułami wtyczek wyjściowych, domyślnie katalog outputs
port - (int) port do komunikacji międzyprocesowej (RMI), domyślnie 9900. Używana wewnętrznie, do wysyłania żądań do działającej w tle instancji aplikacji (status, zamknięcie itp.). Nie ma potrzeby zmiany tej wartości, chyba że jest w konflikcie z inną używającą danego portu usługą lub inną instancją PVD.
debug - (boolean) tryb debug aplikacji (szczegółowe komunikaty) domyślnie false. Powoduje logowanie dużej ilości dodatkowych informacji i w związku z tym należy go używać tylko przy weryfikacji instalacji oraz rozwiązywaniu problemów.
noRepeat - (boolean) wyłączenie lokalnej bazy danych, domyślnie false. Przy bardzo dużej ilości danych może znacząco poprawić sprawność działania aplikacji, jednak uniemożliwia wznawianie wysyłania wiadomości, które z jakiegoś powodu nie zostały poprawnie obsłużone przez wtyczki wyjściowe.
outputThreads (int) ilość wątków używanych jednocześnie przez wtyczki wyjściowe, domyślnie 4. Zwiększenie tej wartości może pozwolić na usprawnienie przepływu informacji kosztem zwiększenia zużycia pamięci oraz obciążenia wtyczek wyjściowych (np. serwera Sync).
manualNativeLibs - (boolean) ręczne ustawianie potrzebnych zewnętrznych bibliotek, domyślnie false. Gdy ta opcja jest wyłączona, aplikacja spróbuje samodzielnie załadować natywne biblioteki, co jest zalecanym zachowaniem. Może jednak zaistnieć konieczność ręcznego ładowania takich bibliotek na nietypowych konfiguracjach systemowych.
repeatTime - (long) odstęp czasowy wznawiania, liczony w sekundach, domyślnie 1800 (30 minut)
validityTime - (long) czas ważności wiadomości, liczony w minutach, domyślnie 43200 (30 dni)
cleanupTime - (long) czas sprzątania bazy danych, liczony w sekundach, domyślnie 3600 (1 godzina)
repeatLimit - (long) ilość wiadomości do załadowania przy pojedynczej próbie powtórzenia, domyślnie 200
heartBeatTime - (long) odstęp czasowy wysyłania na sparowany serwer Sync informacji diagnostycznych (status), liczony w minutach, domyślnie 15 (15 minut). Ustawienie wartości -1 spowoduje wyłączenie wysyłania informacji diagnostycznych.
updateMappingsTime - (long) odstęp czasowy odpytywania sparowanego serwera Sync o aktualizacje mapowań, liczony w minutach, domyślnie 15 (15 minut). Ustawienie wartości -1 spowoduje wyłączenie odpytywania serwera o aktualizacje.
inputDirs - lista ścieżek do lokalizacji bibliotek wtyczek wejściowych. Przydatne, gdy biblioteki znajdują się w rozproszonych katalogach lub w trakcie prac rozwojowych na kodzie źródłowym.
inputEnabled - lista włączonych modułów wtyczek wejściowych. Pozwala włączyć tylko te moduły, które są oczekiwane. Jeśli parametru nie ma lub jest pusty, ładowane są wszystkie moduły wtyczek wejściowych. Wprowadzamy tutaj identyfikatory odpowiednich wtyczek wejściowych.
outputDirs - lista ścieżek do lokalizacji bibliotek wtyczek wyjściowych. Przydatne, gdy biblioteki znajdują się w rozproszonych katalogach lub w trakcie prac rozwojowych na kodzie źródłowym.
outputEnabled - lista włączonych modułów wtyczek wyjściowych. Pozwala włączyć tylko te moduły, które są oczekiwane. Jeśli parametru nie ma lub jest pusty, ładowane są wszystkie moduły wtyczek wyjściowych. Wprowadzamy tutaj identyfikatory odpowiednich wtyczek wyjściowych.

Konfiguracja modułów

Jeśli nie zostało ustawione inaczej, pliki modułów domyślnie zlokalizowane są w katalogach input (wtyczki wejściowe) oraz output (wtyczki wyjściowe). Każdy z tych modułów to plik z rozszerzeniem .jar. Wyłączenie całkowite modułu polega na usunięciu pliku modułu lub - lepiej - zmianie jego rozszerzenia (np. z nazwa_modulu.jar na nazwa_modulu.jar.disabled).

Inną możliwością podania modułów i ich włączenia jest skorzystanie z opcji inputDirs oraz inputEnabled oraz tak samo dla wtyczek wyjściowych outputDirs oraz outputEnabled.

Lokalizacja plików konfiguracyjnych poszczególnych modułów powinna być zgodna ze wzorcem: <user.home>/configs/[typ modułu]/[nazwa modułu]/[nazwa instancji modułu].json, gdzie: * typ modułu to inputs w przypadku wtyczki wejściowej i outputs w przypadku wtyczki wyjściowej. * nazwa modułu to wewnętrzna nazwa modułu (różna od nazwy pliku modułu!) * nazwa instancji modułu nazwa instancji modułu może być dowolna - aplikacja przeszukuje katalog z konfiguracją modułu i każdy z plików konfiguracyjnych ładuje jako kolejną instancję, o nazwie identycznej z nazwą pliku (z pominięciem rozszerzenia .json).

Brak plików konfiguracyjnych dla modułów, które powinny zostać załadowane, poskutkuje błędem inicjalizacji aplikacji. Z drugiej strony, jeżeli plik konfiguracyjny istnieje, ale odpowiadający mu moduł jest wyłączony/usunięty, to taki plik zostanie po prostu zignorowany.

Szczegółowy opis konfiguracji poszczególnych modułów znajduje się w dalszej części instrukcji.

Parowanie z serwerem AMAGE

Parowanie z serwerem AMAGE jest czynnością opcjonalną, jednak jeżeli nie zostanie wykonane, aplikacja nie będzie wysyłać informacji o statusie. Wygenerowany w aplikacji Amage Desktop plik assetsync.conf należy umieścić w katalogu configs i zrestartować aplikację.

Uruchamianie aplikacji z linii poleceń:

Aplikację można uruchomić z linii poleceń:

java -jar pvd-core.jar

Skrót klawiszowy CTRL+C spowoduje przerwanie działania programu. Aplikacja powinna być używana jako usługa systemowa i tak została zaprojektowana, ale powyższy sposób pozwala na szybką weryfikację poprawności konfiguracji i sprawdzenie jej działania.

Aby zmienić katalog startowy, można użyć składni:

java -Duser.home=<katalog> -jar pvd-core.jar

W katalogu głównym aplikacji znajduje się prosty skrypt startowy dla środowiska GNU/Linux.

Instalacja usług systemowych

Poniższa sekcja opisuje kroki wymagane do uruchomienia PVD jako usługi systemowej, osobno dla systemów Windows i Linux.

Windows

Należy przejść do katalogu win_service za wykorzystaniem konsoli/linii komend.

Uwaga: pod niektórymi systemami 64-bitowymi użycie dołączonego pliku prunsrv.exe może okazać się niemożliwe. W takim wypadku należy zastąpić go plikiem dostępnym w win_service/amd64/prunsrv.exe.

Następnie należy zmodyfikować plik service.bat ustawiając wszystkie parametry, które znajdują się w pierwszej części konfiguracji. Pozwala to na zmianę nazwy usługi, ścieżki JVM itp.

SERVICE_NAME - nazwa usługi. Nie mogą istnieć w systemie Windows dwie usługi o tej samej nazwie.
SERVICE_CODE - kod usługi stosowany do systemów logowania. Identyfikator logowania w systemie windows.
DESCRIPTION - opis usługi
CONFIG_HOME - lokalizacja katalogu z konfiguracją/logami itp. Pozwala to na umieszczenie katalogu konfiguracji poza katalogiem instalacji aplikacji, co w dalszym etapie umożliwi aktualizację aplikacji do nowszej wersji bez konieczności przechowywania katalogu konfiguracji w tym samym miejscu.
LOG_LEVEL - domyślny poziom logowania szczegółów. Opcje: Error, Info, Warn, Debug
JAVA_HOME powinien wskazywać na katalog, gdzie zainstalowano środowisko Java.

Instalacja usługi

Po modyfikacji pliku service.bat należy uruchomić go z argumentem install:

service install

Uwaga: konsola (program cmd) musi zostać uruchomiona z uprawnieniami administratora, w przeciwnym wypadku usługa nie zostanie zainstalowana poprawnie.

Powinien pokazać się komunikat o pomyślnym zainstalowaniu usługi, od tego momentu usługa o nazwie PVD Application (lub taka, jaka została mu nadana), powinna być widoczna na liście usług systemu Windows i gotowa do pracy w trybie automatycznego uruchomienia.

Pierwsze uruchomienie usługi należy zainicjować ręcznie. Uwaga: centrum usług należy uruchomić z uprawnieniami administratora.

Automatyczne wznawianie

W celu zabezpieczenia się przed niespodziewanym wyłączeniem aplikacji należy przejść do usług (services) Windows i znaleźć usługę o wybranej nazwie w konfiguracji (domyślnie PVD Application). Następnie wybieramy ustawienia oraz w zakładce odzyskiwanie (recovery) ustawiamy, by za każdym niepowodzeniem usługa się resetowała (preferowane po 0 min). Dzięki czemu aplikacja automatycznie uruchomi się natychmiast po wystąpieniu problemu.

Reinstalacja usługi

Usuwanie usługi aplikacji PVD jest analogiczne do jej instalacji.

Przed usunięciem usługi należy ją znaleźć w widoku usług systemowych (domyślna nazwa PVD Application). Należy ją zatrzymać (w panelu zarządzania usługami systemu Windows. Kolejnym i ostatnim krokiem jest wykonanie poniższego polecenia w konsoli z uprawnieniami administratora:

service remove

Powinien pokazać się komunikat o pomyślnym usunięciu usługi, od tego momentu usługa nie będzie widoczna na liście i nie będzie uruchamiana podczas startu systemu.

Usunięcie należy wykonywać z uprawnieniami administratora. Konsola tekstowa musi być uruchomiona z takimi uprawnieniami.

Linux

Aby zainstalować usługi, należy wykonać dwa skrypty z folderu linux_service, dzięki którym aplikacja będzie startowała przy uruchomieniu systemu.

Przed instalacją należy uzupełnić skrypt startowy pvdapp:

APP_ROOT="/opt/pvd"
JVM_EXE="java"
BIN="pvd-core.jar"
JMX_PORT="9010"
JMX_IP="10.0.0.70"

Należy ustawić: * APP_ROOT - ścieżka do katalogu z aplikacją * JVM_EXE - ścieżka do pliku wykonywalnego Java * BIN - nazwa głównego pliku jar z aplikacją * JMX_PORT - port, na którym będzie można się połączyć z JMX w celach diagnostycznych. * JMX_IP - adres IP, na którym działa usługa JMX

installmxserver - instalowanie serwera moxy jako usługi installpvdapp - instalowanie aplikacji jako usługi

sudo ./installmxserver
sudo ./installpvdapp

Używając skryptu o nazwie "pvdapp", można uruchomić program w trybie: * start - domyślny tryb działania * stop - zatrzymanie pracy aplikacji * restart - restart aplikacji * status - pokazuje aktualny stan modułów

Instalacja z pakietów DEB

Aplikacja PVD jest również dostępna jako pakiet DEB, który można zainstalować na systemach opartych na Debianie (np. Ubuntu). Instalacja pakietu DEB automatycznie konfiguruje aplikację jako usługę systemową. Aby zainstalować pakiet DEB, należy użyć następującego polecenia w terminalu:

sudo dpkg -i pvdapp_<version>.deb

Gdzie <version> to numer wersji pakietu DEB. Po zainstalowaniu pakietu usługa PVD zostanie automatycznie uruchomiona i będzie działać w tle. Można zarządzać usługą za pomocą standardowych poleceń systemd, takich jak:

sudo systemctl start amage-pvd
sudo systemctl stop amage-pvd
sudo systemctl restart amage-pvd
sudo systemctl status amage-pvd

Aplikacja zostaje zainstalowana do katalogu opt/amage/pvd, a pliki konfiguracyjne oraz logi są przechowywane w katalogu /opt/pvd-config.

Automatyczne wznawianie

W celu zabezpieczenia się przed niespodziewanym wyłączeniem aplikacji należy uruchomić z terminala crontab -e, a następnie dopisać na końcu pliku:

*/5 * * * * /sciezka/do/pvdapp start

Gdzie zamiast 5 można podać inna wartość. Jest to odstęp czasowy (w minutach), pomiędzy próbą ponownego uruchomienia aplikacji.

W razie problemów można zmienić domyślny edytor tekstowy np. nano używając polecenia:

export EDITOR=/usr/bin/nano

Monitoring konfiguracji i restart systemu

Aplikacja monitoruje pliki konfiguracyjne wszystkich modułów oraz plik konfiguracyjny aplikacji głównej. W przypadku wykrycia jakiejkolwiek zmiany w plikach konfiguracyjnych aplikacja automatycznie wykonuje restart, aby załadować nowe ustawienia. Dzięki temu administratorzy systemu mogą wprowadzać zmiany w konfiguracji bez konieczności ręcznego restartowania aplikacji, co ułatwia zarządzanie i utrzymanie systemu.

Interfejs WWW

Dostęp do interfejsu webowego

Interfejs webowy aplikacji jest domyślnie uruchamiany na porcie 8080. W przypadku konieczności zmiany portu można to zrobić poprzez przekazanie parametru linii poleceń -Dweb.port—web-server-port=<port> podczas uruchamiania aplikacji. Po pomyślnym włączeniu aplikacji interfejs webowy staje się dostępny pod adresem http://<host>:<port>/, gdzie host to adres IP lub nazwa serwera, na którym uruchomiona jest aplikacja.

Proces uwierzytelniania

Dostęp do interfejsu webowego jest chroniony systemem uwierzytelniania. Okno logowania wyświetlane jest jako pierwsza strona i pozwala użytkownikowi wprowadzić swoją nazwę użytkownika oraz hasło. Aplikacja posiada predefiniowane konto administratora z domyślnymi danymi logowania: nazwa użytkownika admin i hasło admin.

Rysunek 1. Okno logowania

Ze względów bezpieczeństwa, zdecydowanie zaleca się zmianę domyślnego hasła administratora bezpośrednio po pierwszym zalogowaniu do systemu. W przypadku pozostawienia niezmienionego domyślnego hasła, przy każdym kolejnym logowaniu system będzie wyświetlał stosowne ostrzeżenie bezpieczeństwa, przypominając o konieczności jego aktualizacji.

Panel główny aplikacji

Po pomyślnym zalogowaniu użytkownik zostaje przekierowany na stronę główną aplikacji, która prezentuje się w formie przejrzystego dashboardu z kafelkami. Każdy kafelek reprezentuje dostęp do konkretnej sekcji funkcjonalnej aplikacji, umożliwiając intuicyjną nawigację między różnymi modułami systemu. Układ kafelków został zaprojektowany tak, aby najczęściej używane funkcje były łatwo dostępne.

Rysunek 2. Strona startowa

Na górze interfejsu wyświetlane jest ostrzeżenie o niezmienionych domyślnych danych logowania (nazwa użytkownika/hasło), które pozostaje widoczne do momentu ich aktualizacji przez administratora.

Zarządzanie konfiguracją użytkowników

Moduł edycji konfiguracji umożliwia administratorowi zarządzanie kontami użytkowników systemu, w tym zmianę nazw użytkowników oraz haseł. Funkcjonalność ta jest kluczowa dla utrzymania bezpieczeństwa systemu. Po wprowadzeniu zmian w konfiguracji użytkowników konieczne jest zapisanie ustawień i wykonanie restartu aplikacji, aby nowe dane zostały załadowane. Po pomyślnej aktualizacji danych logowania, ostrzeżenia bezpieczeństwa przestają być wyświetlane w interfejsie.

Rysunek 3. Edycja konfiguracji

System zarządzania plikami konfiguracyjnymi

Przeglądarka plików stanowi zaawansowane narzędzie do zarządzania konfiguracją aplikacji. Moduł ten zapewnia pełny dostęp do zawartości folderu configs, w którym przechowywane są wszystkie pliki konfiguracyjne systemu. Użytkownik może przeglądać hierarchiczną strukturę katalogów, nawigować między folderami oraz bezpośrednio edytować pliki konfiguracyjne w formacie JSON. Narzędzie to jest niezbędne do fine-tuningu parametrów aplikacji oraz dostosowywania jej zachowania do specyficznych wymagań środowiska produkcyjnego.

Rysunek 4. Przeglądarka plików

System monitorowania logów

Przeglądarka logów oferuje kompleksowy dostęp do systemu logowania aplikacji i wszystkich jej modułów. Narzędzie to umożliwia przeglądanie zawartości folderu logs, w którym przechowywane są pliki dziennika zdarzeń. Funkcjonalność ta jest kluczowa dla diagnozy problemów, monitorowania wydajności oraz analizy zachowania systemu w czasie rzeczywistym. Administratorzy mogą łatwo lokalizować i analizować konkretne zdarzenia, błędy lub anomalie w działaniu aplikacji.

Rysunek 5. Przeglądarka logów

Podgląd logów w czasie rzeczywistym

Moduł podglądu logów zapewnia możliwość śledzenia aktywności aplikacji oraz wszystkich jej modułów w czasie rzeczywistym. Funkcja ta jest wyposażona w zaawansowane opcje, takie jak automatyczne odświeżanie interfejsu co 5 sekund oraz automatyczne przewijanie do najnowszych wpisów. Te funkcjonalności znacząco ułatwiają monitorowanie bieżącej aktywności systemu oraz szybkie wykrywanie potencjalnych problemów podczas normalnej eksploatacji aplikacji.

Rysunek 6. Podgląd logów

Panel informacji systemowej

Sekcja informacji o systemie prezentuje kompleksowy przegląd stanu infrastruktury aplikacji. Panel ten wyświetla kluczowe informacje techniczne, w tym wszystkie adresy IP interfejsów sieciowych serwera, dokładne wersje wszystkich komponentów systemu oraz szczegółowe statystyki dotyczące liczby uruchomionych i aktywnych modułów. Te informacje są niezbędne dla administratorów systemu podczas diagnostyki, planowania aktualizacji oraz monitorowania ogólnego stanu zdrowia aplikacji.

Rysunek 7. Informacja o systemie

Zarządzanie wtyczkami systemu

Lista wtyczek stanowi centralne miejsce zarządzania wszystkimi modułami rozszerzającymi funkcjonalność aplikacji. Interface ten prezentuje w przejrzystej formie tabelarycznej wszystkie dostępne wtyczki, podzielone na kategorie wejściowe (Input) oraz wyjściowe (Output), wraz z ich bieżącymi statusami działania. Każda wtyczka wyświetlana jest z informacjami o jej stanie (aktywna/nieaktywna) oraz dostępnymi akcjami.

Przycisk View configurations umożliwia przejście do szczegółowego panelu konfiguracji wybranego modułu, gdzie można zarządzać jego ustawieniami. Szczególnie użyteczny jest przycisk Restart all plugins, który pozwala na restart wszystkich modułów bez konieczności zatrzymywania całej aplikacji. Ta funkcjonalność jest niezbędna podczas wdrażania zmian konfiguracyjnych, ponieważ automatycznie wczytuje nowe ustawienia i aktualizuje parametry działania wszystkich wtyczek.

Rysunek 8. Lista wtyczek

Szczegółowe zarządzanie konfiguracją wtyczek

Panel szczegółów konfiguracji wtyczki oferuje zaawansowane narzędzia do kompleksowego zarządzania poszczególnymi modułami. W górnej części interfejsu prezentowana jest lista wszystkich plików konfiguracyjnych powiązanych z daną wtyczką, wraz z możliwością ich bezpośredniej edycji. Administrator ma do dyspozycji funkcje restartu konkretnej wtyczki (bez wpływu na inne moduły), bezpośredni dostęp do dedykowanych logów danego modułu oraz możliwość włączania i wyłączania poszczególnych konfiguracji wtyczki.

Dolna część panelu zawiera intuicyjny formularz dodawania nowych konfiguracji, który umożliwia utworzenie nowego pliku konfiguracyjnego dla wtyczki. Użytkownik może wybrać między utworzeniem pustego pliku konfiguracyjnego (do wypełnienia od podstaw) lub skorzystać z gotowego szablonu opartego na przykładowej konfiguracji, co znacząco przyspiesza proces wdrażania nowych funkcjonalności.

Rysunek 9. Szczegóły wtyczki

Edytor plików konfiguracyjnych

Wbudowany edytor konfiguracji stanowi zaawansowane narzędzie do modyfikacji plików konfiguracyjnych w formacie JSON. Edytor oferuje składnię highlighting, walidację struktury JSON oraz wbudowane mechanizmy sprawdzania poprawności składni. Po zakończeniu edycji i zapisaniu pliku, konieczne jest zrestartowanie odpowiedniego modułu lub całej aplikacji, aby wprowadzone zmiany zostały załadowane i zaczęły obowiązywać w systemie. Proces ten zapewnia spójność konfiguracji i bezpieczne wdrażanie zmian.

Rysunek 10. Edytor pliku (konfiguracji)

Dostępne moduły i ich konfiguracja

Ta część instrukcji opisuje dostępne moduły, z rozróżnieniem, który moduł jest dostawcą, a który odbiorcą.

Wejściowa wtyczka: pvd-input-IEC-62056-21

Nazwa modułu: iec-62056-21

Moduł ten pozwala na odczyt pomiarów z liczników energii elektrycznej zgodnych ze standardem IEC-62056-21. Moduł ten odczytuje dane z portów szeregowych, w co najwyżej jednym wątku na port.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/iec-62056-21/default.json (zamiast default dopuszczalna jest inna, własna nazwa).

 {
    "sleepTime": 30,
    "verboseMode": false,
    "showRawTransmission": false,
    "threadPoolSize":2,
    "sleepBetweenQuerying": 0,
    "disableDelayForUnavailableDevices": false,
    "meterGroupConfigs" : [
        {
            "portName":"/dev/ttyr00",
            "sleepBetweenQuerying": 30,
            "sleepTime": 15,
            "active":true,
            "globalMultipliers":[
            {
                "name":"standard",
                "configs" : {
                    "1.6.0":"{value}*{multiplier}",
                    "1.8.0":"{value}*{multiplier}"
                }
            },
            {
                "name":"pozyton",
                "configs" : {
                    "107":"{value}*{multiplier}",
                    "109":"{value}*{multiplier}"
                }
            }
            ],
            "configs": [
                {
                    "deviceAddress":"51034542",
                    "initialBaudRate": 2400,
                    "timeout": 10000,
                    "active":false,
                    "multiplier":"sqrt(4)/(3^2+2)",
                    "multiplierTemplateName":"standard",
                    "multipliersMap": {
                        "1.6.1":"{value}*12",
                        "1.8.1":"{value}*{multiplier}"
                    }
                },
                {
                    "deviceAddress":"023-0000691",
                    "initialBaudRate": 9600,
                    "timeout": 10000,
                    "meterType": "POZYTON"
                }
            ]
        },
        {
            "portName":"/dev/ttyr02",
            "configs": [
                {
                    "deviceAddress":"51204143",
                    "initialBaudRate": 2400,
                    "timeout": 10000
                },
                {
                    "deviceAddress":"51255055",
                    "initialBaudRate": 2400,
                    "timeout": 10000
                }
            ]
        }
    ]
 }

sleepTime - (int) odstęp czasowy w sekundach pomiędzy ściąganiem danych z licznika, domyślnie 60s, można go skonfigurować globalnie oraz następnie nadpisywać dla danej konfiguracji portu
verboseMode - (boolean) tryb pracy licznika dający więcej informacji, domyślnie false
showRawTransmission - (boolean) pokazuje surową transmisję danych z licznika, domyślnie false
threadPoolSize - (int) maksymalny rozmiar puli wątków wykorzystywany do odczytywania danych z liczników. Jeżeli jest większy od ilości portów, zostaje obcięty do tej ilości.
disableDelayForUnavailableDevices - (boolean) wyłącza automatyczne opóźnienie dla urządzeń, które nie są dostępne (np. brak odpowiedzi). Ułatwia diagnostykę i podłączenie takich urządzeń, gdyż system nie będzie opóźniał kolejnych odczytów w przypadku, gdy urządzenie nie odpowiada. Domyślne opóźnienie to 10 odczytów.
globalMultipliers - (lista) zawierająca unikatową nazwę (name) jak i mapę z adresem odczytanej wartości na sposób w jaki ma być przeliczana dana wartość. Musi zawierać {value} → czyli odczytaną wartość oraz opcjonalnie {multiplier} czyli wyrażenie z danego licznika.
portName - (String) nazwa portu, na którym znajduję się dany licznik (dla Linuxa są to porty tty, dla windows COM, a dla moxy ttyr).
deviceAddress - (String) numer seryjny urządzenia, adres unikalny dla danego urządzenia dzięki, któremu możemy go identyfikować.
initialBaudRate - (int) wartość specyficzna dla danego typu licznika, jest to częstotliwość pracy charakterystyczna również dla danego portu.
sleepBetweenQuerying - (int) odstęp czasowy w sekundach pomiędzy odpytywaniem poszczególnych liczników na danym porcie
meterType - (String) typ licznika, jeżeli jest on zgodny ze standardem, pole może być pominięte. Dostępne wartości: STANDARD (domyślna), POZYTON
active - (boolean) czy port jest aktywny, domyślnie true, opcjonalnie można wyłączyć, dodatkowo gdy port jest aktywny można wyłączyć poszczególny licznik.
multiplier - (String), mnożnik danego licznika. Może to być pojedyncza wartość jak i wyrażenie.
multiplierTemplateName - (String) nazwa z wykorzystywanego wzorca, musi to być nazwa występująca w globalMultipliers w polu name * multipliersMap - (Map) unikalna mapa dla danego licznika z przelicznikami wartości. Musi występować {value} w przeciwnym wypadku zwracana jest wartość domyślna odczytana z licznika. Jeżeli taki sam parametr występuje w globalMultipliers zostaję on nadpisany tym przelicznikiem.

W przypadku, gdy urządzenie nie odpowiada (brak komunikacji) i taki efekt występuje przez 3 kolejne próby odczytu, to system automatycznie przestaje próbować komunikować się z urządzeniem przez 10 kolejnych odczytów. Pozwala to na ograniczenie blokowania komunikacji z innymi urządzeniami na tej samej magistrali. Po poprawnym odczycie, system automatycznie przywraca odczyt z ustaloną, maksymalną częstotliwością. Wyłączyć to zachowanie (np. do celów diagnostycznych) możemy za pomocą globalnej opcji disableDelayForUnavailableDevices

Mapowania

Klucz mapowany na UUID jest zbudowany z numeru seryjnego urządzenia, znaku # oraz ustandaryzowanego kodu odczytywanej wartości, np. 38547626#1.8.0 (nr seryjny 38547626, kod wartości 1.8.0) lub 023-0000691#102.1 (nr seryjny 023-0000691, kod wartości 102.1).

Wejściowa wtyczka: pvd-input-modbus-tcp

Nazwa modułu: modbus-tcp

Moduł ten pozwala na odczyt wartości po protokole modbus TCP (np. z falownika).

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/modbus-tcp/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca to konkretne źródło danych).

Wersja 1 konfiguracji

Wersja 1 konfiguracji opisuje komunikację za pomocą podstawowych typów danych. Zachowana dla kompatybilności z istniejącymi konfiguracjami. Rozpoznawana przez trzy parametry w definicji rejestru np. 0:float:100.

 {
      "debug": false,
      "devices":[
            {
                "ip":"192.168.1.104",
                "port":502,
                "sleepTime":10,
                "description":"Falownik Testowy",
                "enabled":"true",
                "useLoHiWordOrder": "false",
                "data": {
                    "0:float:100":"fd005850-86c9-498e-8ab2-d3d7a739daa6",
                    "1:int:0":"2a9ed604-bac9-44b9-84b0-01f91f3b4ee4",
                    "2:float:100":"b063bc0a-06ec-40c8-a5fa-721275443388",
                    "3:float:10":"6028f30e-205a-4fa6-8e9a-0fc4ed11d979",
                    "4:float:10":"46f2b46c-da21-425a-a118-95a8c09b4422",
                    "5:float:10":"38ce3bb2-33b9-49ad-8d85-12eec0020653",
                    "6:int:0":"a2f75e59-96df-4b83-81fe-8e6e96e24330",
                    "7:float:10":"41be100f-ba9a-41a2-bd51-801fc922157f"
                }
            },

            {
                "ip":"192.168.1.105",
                "port":502,
                "sleepTime":10,
                "description":"Falownik Testowy 2",
                "enabled":"false",
                "data": {
                    "0:float:100":"fd005850-86c9-498e-8ab2-d3d7a739daa6",
                    "1:int:0":"2a9ed604-bac9-44b9-84b0-01f91f3b4ee4",
                    "2:float:100":"b063bc0a-06ec-40c8-a5fa-721275443388",
                    "3:float:10":"6028f30e-205a-4fa6-8e9a-0fc4ed11d979",
                    "4:float:10":"46f2b46c-da21-425a-a118-95a8c09b4422",
                    "5:float:10":"38ce3bb2-33b9-49ad-8d85-12eec0020653",
                    "6:int:0":"a2f75e59-96df-4b83-81fe-8e6e96e24330",
                    "7:float:10":"41be100f-ba9a-41a2-bd51-801fc922157f"
                }
            }

        ]
}

Wersja 2 konfiguracji

Wersja 2 konfiguracji opisuje komunikację za pomocą wszystkich znanych typów danych MODBUS. Stara się obsłużyć wszystkie typy danych.

 {
      "debug": false,
      "devices":[
            {
                "ip":"192.168.1.104",
                "port":502,
                "unitId":1,
                "addressShift":-1,
                "sleepTime":10,
                "useLoHiWordOrder": "false",
                "description":"Falownik Testowy",
                "enabled":"true",
                "data": {
                    "40072:uint32:Power Active:2": "b2ddc792-cf40-42b7-b9ce-82eb68928ac3",
                    "40005:string32:Manufacturer:0": "c2ddc792-cf40-42b7-b9ce-82eb68928ac3"
                }
            }

        ]
 }

Dane definicyjne:

debug - (boolean) flaga włączona pozwala na logowanie w logach/konsoli informacji z biblioteki komunikacyjnej oraz wyświetlania danych wysyłanych i odbieranych w formacie HEX

Dane ogólne zawierają informacje o poszczególnych urządzeniach.

ip - (String) adres ip urządzenia.
port - (int) port po którym będziemy się łączyć (standardowo 502).
unitId - (int) numer jednostki modbus (zwykle 1)
addressShift - (int) przesunięcie adresów np. -1. Nakładane zawsze w przypadku odczytu. Pozwala na definicję w mapowaniu rzeczywistych adresów z dokumentacji a jednocześnie odpowiednim przesunięciu zgodnie z protokołem danego urządzenia. <Opcja>
addressBase - (int) bazowa wartość adresu. Dodawana zawsze do adresu. <Opcja>
description - (String) opis urządzenia.
useLoHiWordOrder - Przy odczycie DWORD (dwóch rejestrów) domyślnie stosujemy ułożenie rejestrów HiLo czyli najpierw najwyższy bajt a potem w dół do najniższego. Przy włączeniu tej opcji stosujemy odwrotne ułożenie ALE tylko w przypadku rejestrów. Czyli Jeśli odczytamy bajty z DWÓCH rejestrów [A] [B] [C] [D] to ułożenie HiLo będzie MSB [A] [B] [C] [D] LSB, natomiast w przypadku ułożenia LoHi będzie to MSB [C] [D] [A] [B] LSB.
sleepTime - (int) odstęp czasowy w sekundach do odczytu protokołu.
enabled - (boolean) flaga czy chcemy odczytywać dane urządzenie.
data - (Map<String, UUID>) Mapa rejestrów które będziemy odczytywać, oraz UUID pod jakie mają być wrzucane.

Format mapy rejestrów, zawiera parę konfiguracji rejestru i UUID ustawień parametru.

Wersja 1 konfiguracji

Konfiguracja rejestru składa się z trzech pól:

numer rejestru (np. 2003)
typu danych - int lub float
dzielnik - określa przez jaką liczbę będzie dzielony odczyt np. dla odczytu rejestru 1000 z wartością 1234 o typie float i dzielniku 100 otrzymujemy wynik 12,34

Wersja 2 konfiguracji

Konfiguracja rejestru składa się z 4 pól:

numer rejestru (np. 2003)
typ danych - uint16, uint32, uint64, int16, int32, bitfield16, enum16, acc32, float32, string32, string16
opis - opis dla użytkownika (pojawia się w logach)
dzielnik - określa przez jaką liczbę będzie dzielony odczyt np. dla odczytu rejestru 1000 z wartością 1234 o typie float i dzielniku 100 otrzymujemy wynik 12,34. Zawsze stosujemy 2 znaki po przecinku

Wejściowa wtyczka: pvd-input-modbus-rtu

Nazwa modułu: modbus-rtu

Moduł ten pozwala na odczyt wartości z urządzeń po protokole modbus RTU, czyli protokół MODBUS po magistralach szeregowych typu RS-232/RS-485. W dokumentacji pomijamy mechanizm fizycznego podłączenia urządzenia/konwertera RS do danego systemu, na którym jest zainstalowana aplikacja PVD.

Do podłączeń można wykorzystać również urządzenia pośredniczące typu Moxa N-Port (lub podobny). W tym przypadku zwykle istnieje dodatkowe oprogramowanie narzędziowe danego producenta, które umożliwia udostępnienie portów szeregowych danego urządzenia jako wirtualne porty szeregowe czy to w środowisku Windows czy Linux. Należy odnieść się do dokumentacji producenta, aby podłączyć/zamapować odpowiednie porty.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/modbus-rtu/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca to konkretne źródło danych). Może istnieć dowolna liczba takich konfiguracji np. z podziałem na poszczególne porty szeregowe.

Konfiguracja

Konfiguracja podzielona jest na drzewo danych. Urządzenia fizyczne (jednostki komunikacyjne) grupowane są w porty komunikacyjne (szeregowe) o takich samych parametrach komunikacyjnych. Czyli mamy hierarchię konfiguracja ogólna → porty → urządzenia.

Przykładowy plik konfiguracji znajduje się poniżej. Zawiera on definicję jednego portu szeregowego oraz jednego urządzenia podpiętego do tego portu.

 {
    "sleepTime": 30,
    "debug": false,
    "threadPoolSize": 1,
    "sleepBetweenQuerying": 2,
    "disableDelayForUnavailableDevices": false,
    "ports": [
        {
            "sleepTime": 3,
            "sleepBetweenQuerying": 1,
            "active": true,
            "port": "/dev/ttyUSB0",
            "baudRate": 9600,
            "dataBits": 8,
            "stopBits": 1,
            "parity": "None",

            "devices": [
                {
                    "name": "Test modbus RTU device",
                    "description": "additional description for the device",
                    "active": true,
                    "unitId": 1,
                    "addressShift": 0,
                    "addressBase": 0,
                    "useLoHiWordOrder": true,
                    "sleepTime": 5,
                    "data": {
                        "0:float32:Current Voltage - clamp A:0": "97c95bd0-abe4-4770-bdef-23b6f075cd0f",
                        "2:float32:Current Voltage - clamp B:100": "97d95bd0-abe4-4770-bdef-23b6f075cd0f"
                    }
                }
            ]
        }
    ]
 }

Przyjęto, że jeden port szeregowy posiada swoje definicje tj. prędkość bitową, parametry komunikacji jednolite dla wszystkich urządzeń podpiętych pod ten port. Wynika to z właściwości łącza danych. Różne prędkości/parametry mogą spowodować błędne działanie urządzeń spiętych w tej samej magistrali.

Dane definicyjne ogólne:

sleepTime - (int) odstęp czasowy w sekundach pomiędzy ściąganiem danych z urządzenia, domyślnie 60s, można go skonfigurować globalnie oraz następnie nadpisywać dla danej konfiguracji portu
debug - (boolean) flaga włączona pozwala na logowanie w logach/konsoli informacji z biblioteki komunikacyjnej oraz wyświetlania danych wysyłanych i odbieranych w formacie HEX
threadPoolSize - (int) maksymalny rozmiar puli wątków wykorzystywany do odczytywania danych z urządzeń. Jeżeli jest większy od ilości portów, zostaje obcięty do tej ilości.
sleepBetweenQuerying - (int) odstęp czasowy w sekundach pomiędzy odpytywaniem poszczególnych urządzeń na danym porcie. Można nadpisywać go w poszczególnych portach.
disableDelayForUnavailableDevices - (boolean) wyłącza automatyczne opóźnienie dla urządzeń, które nie są dostępne (np. brak odpowiedzi). Ułatwia diagnostykę i podłączenie takich urządzeń, gdyż system nie będzie opóźniał kolejnych odczytów w przypadku, gdy urządzenie nie odpowiada. Domyślne opóźnienie to 10 odczytów.

Dane portu szeregowego:

sleepTime - (int) odstęp czasowy w sekundach pomiędzy ściąganiem danych z urządzenia,
sleepBetweenQuerying - (int) odstęp czasowy w sekundach pomiędzy odpytywaniem poszczególnych urządzeń na danym porcie
active - czy port jest aktywny i odczytujemy z niego dane
port - nazwa portu np. COM1, /dev/ttyUSB0 itp.
baudRate - prędkość bitowa np. 9600
dataBits - liczba bitów danych - 7/8
stopBits - liczba bitów stopu - 0/1
parity - parzystość komunikacji - wartości: Even, Mark, None, Odd, Space

Dane poszczególnego urządzenia:

name - (String) nazwa urządzenia (pojawia się w logach)
description - (String) opis urządzenia - opisowo pole dla konfiguracji
active - (boolean) flaga czy chcemy odczytywać dane urządzenie.
unitId - (int) numer jednostki modbus (zwykle 1)
addressShift - (int) przesunięcie adresów np. -1. Nakładane zawsze w przypadku odczytu. Pozwala na definicję w mapowaniu rzeczywistych adresów z dokumentacji a jednocześnie odpowiednim przesunięciu zgodnie z protokołem danego urządzenia. <Opcja>
addressBase - (int) bazowa wartość adresu. Dodawana zawsze do adresu. <Opcja>
useLoHiWordOrder - Przy odczycie DWORD (dwóch rejestrów) domyślnie stosujemy ułożenie rejestrów HiLo czyli najpierw najwyższy bajt a potem w dół do najniższego. Przy włączeniu tej opcji stosujemy odwrotne ułożenie ALE tylko w przypadku rejestrów. Czyli Jeśli odczytamy bajty z DWÓCH rejestrów [A] [B] [C] [D] to ułożenie HiLo będzie MSB [A] [B] [C] [D] LSB, natomiast w przypadku ułożenia LoHi będzie to MSB [C] [D] [A] [B] LSB.
sleepTime - (int) odstęp czasowy w sekundach do odczytu protokołu.
data - (Map<String, UUID>) Mapa rejestrów, które będziemy odczytywać oraz UUID, pod jakie mają być wrzucane.

Format mapy rejestrów, zawiera parę konfiguracji rejestru i UUID ustawień parametru są zgodne z wersją 2 konfiguracji Modbus TCP tj.

Wersja (2) konfiguracji

Konfiguracja rejestru składa się z 4 pól:

numer rejestru (np. 2003)
typ danych - uint16, uint32, uint64, int16, int32, bitfield16, enum16, acc32, float32, string32, string16
opis - opis dla użytkownika (pojawia się w logach)
dzielnik - określa przez jaką liczbę będzie dzielony odczyt np. dla odczytu rejestru 1000 z wartością 1234 o typie float i dzielniku 100 otrzymujemy wynik 12,34. Zawsze stosujemy 2 znaki po przecinku

W przypadku, gdy urządzenie nie odpowiada (brak komunikacji) i taki efekt występuje przez 3 kolejne próby odczytu, to system automatycznie przestaje próbować komunikować się z urządzeniem przez 10 kolejnych odczytów. Pozwala to na ograniczenie blokowania komunikacji z innymi urządzeniami na tej samej magistrali. Po poprawnym odczycie system automatycznie przywraca odczyt z ustaloną, maksymalną częstotliwością. Wyłączyć to zachowanie (np. do celów diagnostycznych) możemy za pomocą globalnej opcji disableDelayForUnavailableDevices

Wejściowa wtyczka: pvd-file-content-reader

Nazwa modułu: file-content

Moduł ten pozwala na okresowy odczyt wartości z pliku. Pozwala np. na odczyt danych przechowywanych w systemie /proc lub w innych plikach np. wartości parametrów czujników 1-Wire wykorzystujących widok na system plików.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/file-content/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca to konkretne źródło danych).

 {
  "pathFile":"/path/to/file",
  "sleepTime":10,
  "uuid":"f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7",
  "charsetName":"UTF-8"
 }

pathFile - (path) ścieżka do pliku, z którego chcemy czytać dane.
sleepTime - (int) odstęp czasowy w sekundach do odczytu z pliku.
uuid - (uuid) unikalny numer uuid parametru dla tego pliku (taki sam jak w aplikacji).
charsetName - (String) opcjonalny wybór kodowania, domyślnie UTF-8

Odbiorca: pvd-output-params-rest

Nazwa modułu: params-rest

Moduł ten pozwala na przekazywanie wiadomości do wybranego serwera Sync.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/output/params-rest/default.json. (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca odbiorcę).

 {
    "connectionTimeout": 5,
    "skipTime": 180,
    "restConfig": {
        "apiKey": "666f6f",
        "apiSecret": "626172",
        "protocol": "http",
        "host": "localhost",
        "context": "",
        "port": 5000,
        "deviceUUID": "26f4c3a7-3820-4d0f-844e-134da324a40b"
    }
 }
----

connectionTimeout - (int) czas (w sekundach), po którym połączenie zostanie uznane za nieudane, domyślnie 5. Zapobiega blokowaniu się wyjścia.
skipTime - (int) czas (w sekundach), który musi minąć po nieudanym połączeniu, zanim zostanie podjęta ponowna próba, domyślnie 180. Zapobiega blokowaniu się wyjścia.

Wartość pola restConfig wskazuje na konfigurację połączenia z serwerem Sync. Jeżeli jest to ten sam serwer, z którym aplikacja została sparowana, wystarczy wstawić tutaj konfigurację z pliku assetsync.conf.

apiKey - (String) apiKey urządzenia
apiSecret - (String) apiSecret urządzenia
protocol - (String) rodzaj używanego protokołu do wysyłania danych
host - (String) adres serwera assetsync
context - (String) kontekst serwera assetsync
port - (int) numer używanego portu do komunikacji z assetsync
deviceUUID - (uuid) unikalny uuid urządzenia

Wejściowa wtyczka: pvd-input-test

Nazwa modułu: example

Generuje przypadkowe dane w odstępach czasu.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/example/default.json. (zamiast default dopuszczalna jest inna, własna nazwa).

Wszystkie pola są opcjonalne.

 {
    "threadPoolSize": 1,
    "generatorsQuantity": 1,
    "sleepTime": 1000,
    "payloadSize": 1,
    "parameterUUID": "ef466d4f-ec72-44c5-939c-287e7646b125"
 }

threadPoolSize - (int) ilość wątków użytych do generowania wartości, domyślnie 1.
generatorsQuantity - (int) ilość generatorów.
sleepTime - (int) czas (w milisekundach) co ile odpytywać generator o wartość.
payloadSize - (int) ilość wygenerowanych wartości.
parameterUUID - (UUID) parametr, którego dotyczy generowana wartość

Odbiorca: pvd-output-test

Nazwa modułu: example

Loguje wszystkie odebrane wiadomości, nie przekazuje ich dalej.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/output/example/default.json. (zamiast default dopuszczalna jest inna, własna nazwa).

Ten moduł nie pozwala na konfigurację, plik konfiguracyjny wygląda zawsze tak samo:

{}

Wejściowa wtyczka: pvd-input-dlms

Nazwa modułu: dlms

Dostawca DLMS pozwala na komunikację z urządzeniami z wykorzystaniem protokołu DLMS. Konfiguracja dostawcy polega na określeniu parametrów dostępowych dla urządzeń oraz listy kodów OBIS, które będą odczytywane z tych urządzeń.

 {
    "sleepTime": 30,
    "threadPoolSize":2,
    "obisCodes": ["1.1.2.6.0.255"],
    "meterGroupConfigs" : [
        {
            "portName":"/dev/ttyUSB0",

            "configs" : [
                {
                    "deviceAddress":"9569",
                    "initialBaudRate": 9600,
                    "timeout": 10000,
                    "logicalId":1,
                    "clientId":16
                }
            ]
        }
    ]
 }

threadPoolSize - (int) ilość wątków użytych do generowania wartości, domyślnie 1.
obisCodes - (list) lista kodów OBIS, które będą odczytywane z urządzeń
meterGroupConfig - (struct) struktura konfiguracji liczników
deviceAddress - (string) numer seryjny urządzenia
logicalId - (int) logiczne ID urządzenia w ramach komunikacji
clientId (int) identyfikator klienta dostępowego

Mapowanie na parametry realizowane za pomocą konfiguracji mapowania sync.

Dostawca: pvd-input-sql

Nazwa modułu: sql

Mechanizm pobierania danych z zewnętrznego źródła w postaci tabeli z pomiarami. Definicja dostawcy realizowana za pomocą przykładowej konfiguracji z dostępem do serwera MS SQL:

 {
    "dbDriver":"com.microsoft.sqlserver.jdbc.SQLServerDriver",
    "dbUrl":"jdbc:sqlserver://100.100.100.100\\INSTANCE:1433;databaseName=database;",
    "dbUser":"amage",
    "dbPassword":"amage",
    "tableName":"POMIARY",
    "timeBetweenDispatch": 120
 }

dbDriver - klasa sterownika JDBC do dostępu. Dostępne MS SQL server oraz PostgreSQL.
dbUrl - URL w formacie JDBC dostępu do bazy danych
dbUser - użytkownik do autoryzacji dostępu
dbPassword - hasło użytkownika do autoryzacji dostępu
tableName - nazwa tabeli źródłowej, z której pobieramy dane
timeBetweenDispatch - czas pomiędzy skanowaniami tabeli źródłowej w sekundach.

Kolumny w tabeli źródłowej muszą mieć następującą strukturę:

DateTime - date - data odczytu
TagName - string - nazwa parametru
Value - string - wartość parametru

Po odczycie następuje skasowanie całej zawartości tabeli pomiarów (w danej sesji).

Mapowanie na parametry realizowane za pomocą konfiguracji mapowania sync.

Wyjściowa wtyczka: pvd-output-params-sql

Nazwa modułu: params-sql

Odbiera danych parametrów z systemu Sync oraz przekazuje je do tabel zewnętrznych o ustalonej strukturze.

Kolumny w tabeli źródłowej muszą mieć następującą strukturę:

[1] - date - data odczytu
[2] - string - nazwa parametru
[3] - string - wartość parametru

Przykładowy plik konfiguracji:

 {
    "dbDriver":"com.microsoft.sqlserver.jdbc.SQLServerDriver",
    "dbUrl":"jdbc:sqlserver://100.100.100.100\\INSTANCE:1433;databaseName=database;",
    "dbUser":"amage",
    "dbPassword":"amage",

    "targetParams": [
        {
            "valueName":"00MKA10CE901",
            "uuid":"37073696-74cf-4a40-847f-bae4a2debedc",
            "multiplier":1
        },
        {
            "valueName":"00AEA00CE902",
            "uuid":"65a56440-018b-4ddd-b1f9-ae6cce642e31",
            "multiplier":1
        },
        {
            "valueName":"00AEA00CE901",
            "uuid":"ee6e896d-a0ab-4932-8635-5f25e6e9ef63",
            "multiplier":1
        }

    ],

    "table" : [
        {
            "tableName":"dbo.Liczniki_E_01M",
            "time":60
        },
        {
            "tableName":"dbo.Liczniki_E_15M",
            "time":900
        }
    ]
 }

dbDriver - klasa sterownika JDBC do dostępu. Dostępne MS SQL server oraz PostgreSQL.
dbUrl - URL w formacie JDBC dostępu do bazy danych
dbUser - użytkownik do autoryzacji dostępu
dbPassword - hasło użytkownika do autoryzacji dostępu
targetParams - docelowe parametry do eksportu
table - tabele, do których będą eksportowane dane
valueName - nazwa docelowego parametru do wpisania do tabeli docelowej
uuid - UUID ustawień parametru w systemie AMAGE do eksportu do zewnętrznego systemu
multiplier - mnożnik do wykonania w przypadku danych liczbowych
tableName - nazwa tabeli do eksportu
time - okres wysyłania danych

Takie podejście pozwala na eksport danych w różnych okresach do różnych tabel.

Wyjściowa wtyczka: pvd-failure

Nazwa modułu: failure

Testowy odbiorca danych, który na odebranie jakiejkolwiek wiadomości generuje odpowiedź DispatchResult.FAILURE.

Dostawca: pvd-input-huawei-pv-rest

Nazwa modułu: huawei-pv-rest

Mechanizm pobierania danych dotyczących przemienników częstotliwości wykorzystywanych w systemach fotowoltaicznych. Komunikacja następuje poprzez interfejs HTTP REST do zewnętrznego serwera firmy Huawei (w momencie pisania dokumentacji serwery w domenie fusionsolar.huawei.com). Oznacza to, że aplikacja musi mieć dostęp do ww. adresu i adresów potomnych w tej domenie, aby umożliwić dostęp do tych danych.

 {
    "devices": [
        {
            "description": "Huawei PV - SUN2000-15KTL-M0 - SN: 123",
            "userName": "user",
            "systemCode": "systemcode",
            "stationCode": "xxx",
            "deviceId": 0,
            "deviceTypeId": 0,
            "sleepTime": 10,
             "data": {
                 "grid_frequency:Grid frequency:0": "d119b575-0604-4404-b954-017a828fe98d"
             },
            "enabled": true
        }
    ]
 }

description - Opis urządzenia
userName - użytkownik do logowania do systemu REST
systemCode - kod systemowy do logowania do systemu REST
stationCode - identyfikator stacji
deviceId - numer urządzenia
deviceTypeId - typ urządzenia
sleepTime - czas przerw pomiędzy odczytamy (sekundy)
enabled - włączenie/wyłączenie konfiguracji
data - dane mapowania parametrów na UUID ustawień parametrów

Szkielet konfiguracji można wygenerować bezpośrednio w aplikacji AMAGE dla danego urządzenia. W menu kontekstowym zasobu znajdują się akcje generacji pliku szkieletowego.

Po utworzeniu ww. pliku szkieletowego można przystąpić do dalszej konfiguracji. Najważniejsze to posiadać dane userName/systemCode otrzymane od wdrożeniowców systemu Huawei (lub bezpośrednio z Huawei Solar). Dane te wpisujemy do konfiguracji.

Jeśli nie znamy identyfikatora stacji, ID urządzenia lub jego typu, to pozostawiając domyślne wartości "xxx" lub 0 system w trakcie uruchomienia wyświetli wszystkie dostępne dane, z których będzie można skopiować te informacje. Informacje te można skopiować również z interfejsu WWW dostępu do danych przez Huawei.

Po wypełnieniu wszystkich danych należy odpowiednio skonfigurować mapowania ustawień parametrów. Składa się on z trzech segmentów:

<nr funkcji>:<nazwa>:<skalowanie>

Gdzie:

Numer funkcji to nazwa funkcji ze słownika poniżej. Odpowiada parametrom możliwym do odczytu przez urządzenia
Nazwa - pomocniczy parametr, wyświetlany w logach PVD i pochodzących z konfiguracji parametrów w aplikacji AMAGE
Skalowanie - 0 → brak skalowania. Jeśli > 0 to wartość mierzona zostanie PODZIELONA na daną wartość. Pozwala to np. odczytać dane w kWh i zamienić na MWh bezpośrednio przed przesłaniem do systemu głównego.

Wyjściowa wtyczka: pvd-output-csv

Nazwa modułu: file-csv

Moduł pozwala zapisać dane lokalnie w środowisku uruchomieniowym aplikacji PVD. Dane odbierane są przez standardowe metody od dostawców danych, a następnie zapisywane w pliku formatu CSV (separator średnik ;) w katalogu docelowym. Po włączeniu opcji separateFiles na true system po odebraniu wiadomości zapisuje je w osobnych plikach dla każdego identyfikatora UUID.

W przypadku separateFiles = false w katalogu docelowym tworzony jest plik o nazwie output.csv i do niego zapisywane są wartości w formacie:

Znacznik czasu (ISO).
Identyfikator UUID parametru.
Odczytana wartość parametru.

np.

2022-05-12T13:10:44.888;b89da96b-d444-4adc-93b7-b9b7e0798c12;11341;

W przypadku separateFiles = true tworzone są osobne pliki. Dla ww. przypadku utworzony zostanie w katalogu docelowym plik o nazwie b89da96b-d444-4adc-93b7-b9b7e0798c12.csv i zawartości przykładowej (jeden rekord):

2022-05-12T13:10:44.888;11341;

Pliki są uzupełniane tj. jeśli istnieją i nie są puste to wartości zostaną dopisane na końcu pliku

Przykład konfiguracji:

 {
    "resultPath": "/home/user/result_folder",
    "separateFiles": true
 }

Wejściowa wtyczka - OPC-UA

Nazwa modułu: opc-ua

Mechanizm pobierania danych z serwerów OPC-UA. Moduł pozwala na połączenie z serwerem OPC-UA, autoryzację oraz cykliczny odczyt wybranych węzłów danych.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/opc-ua/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca to konkretne źródło danych).

{
    "endpointUrl": "opc.tcp://localhost:4840",
    "readIntervalMs": 1000,
    "username": "opcuser",
    "password": "opcpassword",
    "nodes": [
        {
            "nodeId": "ns=2;s=Device1.Temperature",
            "parameterUuid": "f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7"
        },
        {
            "nodeId": "ns=2;s=Device1.Pressure",
            "parameterUuid": "a2b3c4d5-e6f7-8901-2345-6789abcdef01"
        }
    ]
}

endpointUrl - (String) adres URL serwera OPC-UA w formacie opc.tcp://host:port
readIntervalMs - (int) interwał odczytu danych w milisekundach, domyślnie 1000
username - (String) nazwa użytkownika do autoryzacji (opcjonalne)
password - (String) hasło użytkownika do autoryzacji (opcjonalne)
nodes - (list) lista węzłów OPC-UA do odczytu

Konfiguracja węzła OPC-UA:

nodeId - (String) identyfikator węzła OPC-UA w standardowym formacie (np. ns=2;s=Device1.Temperature)
parameterUuid - (UUID) unikalny identyfikator parametru w systemie AMAGE, do którego będą mapowane dane z tego węzła

Nadawca - Milesight IoT LoRaWAN

Nazwa modułu: milesight

Mechanizm odbierania danych z urządzeń IoT firmy Milesight przez interfejs HTTP webhooks. Moduł udostępnia endpointy HTTP do odbierania danych telemetrycznych z urządzeń LoRaWAN, takich jak czujniki temperatury i wilgotności.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/milesight/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca to konkretne źródło danych).

{
    "threadPoolSize": 1,
    "devices": [
        {
            "deviceType": "EM_300_TH",
            "deviceEui": "24e124136e302752",
            "parameters": {
                "TEMPERATURE": "f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7",
                "HUMIDITY": "a2b3c4d5-e6f7-8901-2345-6789abcdef01"
            }
        }
    ]
}

threadPoolSize - (int) rozmiar puli wątków do obsługi żądań HTTP, domyślnie 1
devices - (list) lista urządzeń Milesight skonfigurowanych do odbioru danych

Konfiguracja urządzenia Milesight:

deviceType - (enum) typ urządzenia Milesight. Dostępne wartości: EM_300_TH (czujnik temperatury i wilgotności)
deviceEui - (String) unikalny identyfikator urządzenia (Device EUI) w sieci LoRaWAN
parameters - (map) mapowanie parametrów urządzenia na UUID parametrów w systemie AMAGE

Dostępne parametry dla urządzenia EM_300_TH:

TEMPERATURE - temperatura w stopniach Celsjusza
HUMIDITY - wilgotność względna w procentach

Moduł udostępnia następujące endpointy HTTP, do których wysyła bramka LoRaWAN Milesight dane telemetryczne:

/pvd-input-milesight/data - endpoint do odbierania danych telemetrycznych (metoda POST)
/pvd-input-milesight/status - endpoint statusu modułu (metoda GET)
/pvd-input-milesight/error - endpoint testowy do generowania błędów

Format danych wejściowych (JSON):

{
    "applicationID": 1,
    "devEUI": "24e124136e302752",
    "deviceName": "temperature - 01",
    "humidity": 39,
    "temperature": 21.2
}

Należy skonfigurować bramkę LoRaWAN Milesight, aby wysyłała dane telemetryczne do endpointu /pvd-input-milesight/data aplikacji PVD. W przeciwnym razie moduł nie będzie odbierał żadnych danych.

Wyjściowa wtyczka - interfejs webhooks

Nazwa modułu: webhook

Mechanizm wysyłania danych do zewnętrznych systemów przez interfejs HTTP webhooks. Moduł przekształca otrzymane dane na format JSON i wysyła je metodą POST do skonfigurowanego adresu URL.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/output/webhook/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca docelowy system).

{
    "outputWebhook": "https://example.com/api/data"
}

outputWebhook - (String) adres URL zdalnego systemu, do którego będą wysyłane dane w formacie JSON

Format wysyłanych danych JSON:

[
    {
        "timestamp": "2025-01-24T10:30:15",
        "valueUUID": "f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7",
        "valueString": "21.5"
    },
    {
        "timestamp": "2025-01-24T10:30:15",
        "valueUUID": "a2b3c4d5-e6f7-8901-2345-6789abcdef01",
        "valueString": "65.2"
    }
]

Parametry wysyłanych danych:

timestamp - znacznik czasowy w formacie ISO LocalDateTime
valueUUID - unikalny identyfikator parametru w systemie AMAGE
valueString - wartość parametru w formacie tekstowym

Moduł automatycznie obsługuje:

Timeout połączenia (5 sekund)
Certyfikaty SSL self-signed
Weryfikację statusu odpowiedzi HTTP (200-299 = sukces)
Logowanie błędów komunikacji

Wyjściowa wtyczka - plik CSV do serwera SFTP

Nazwa modułu: sftp-csv

Mechanizm eksportu danych do plików CSV i przesyłania ich na zdalny serwer SFTP. Moduł generuje pliki CSV z danymi parametrów i automatycznie przesyła je na skonfigurowany serwer SFTP.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/output/sftp-csv/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca docelowy serwer).

{
    "serverAddress": "sftp.example.com",
    "serverPort": 22,
    "username": "sftpuser",
    "password": "sftppassword",
    "resultPath": "/upload/data",
    "separateFiles": true
}

serverAddress - (String) adres serwera SFTP
serverPort - (int) port serwera SFTP, domyślnie 22
username - (String) nazwa użytkownika do autoryzacji SFTP
password - (String) hasło użytkownika do autoryzacji SFTP
resultPath - (String) ścieżka do katalogu docelowego na serwerze SFTP
separateFiles - (boolean) czy dane mają być zapisywane w osobnych plikach dla każdego parametru, domyślnie false

Format plików CSV:

Gdy separateFiles = false (jeden plik ze wszystkimi parametrami):

2025-01-24T10:30:15;f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7;21.5;
2025-01-24T10:30:15;a2b3c4d5-e6f7-8901-2345-6789abcdef01;65.2;

Gdy separateFiles = true (osobny plik dla każdego parametru):

2025-01-24T10:30:15;21.5;

Struktura kolumn CSV: * Kolumna 1: znacznik czasowy w formacie ISO LocalDateTime * Kolumna 2: UUID parametru (tylko gdy separateFiles = false) lub wartość parametru (gdy separateFiles = true) * Kolumna 3: wartość parametru (tylko gdy separateFiles = false)

Moduł automatycznie obsługuje: * Tworzenie tymczasowych plików CSV * Nawiązywanie połączenia SFTP z wyłączoną weryfikacją kluczy hosta * Przesyłanie plików na serwer SFTP * Usuwanie tymczasowych plików po przesłaniu * Logowanie błędów połączenia i transferu

Wtyczka wejściowa - MQTT

Nazwa modułu: mqtt

Mechanizm odbierania danych z brokera MQTT. Moduł nawiązuje połączenie z brokerem MQTT, subskrybuje wybrane tematy i przekazuje otrzymane wiadomości do systemu AMAGE.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/mqtt/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca konkretny broker MQTT).

{
    "brokerUrl": "tcp://mqtt.example.com:1883",
    "clientId": "amage-pvd-client",
    "username": "mqttuser",
    "password": "mqttpassword",
    "mqttMessageList": [
        {
            "topic": "sensors/temperature/room1",
            "targetUuid": "f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7",
            "qos": 1
        },
        {
            "topic": "sensors/humidity/room1",
            "targetUuid": "a2b3c4d5-e6f7-8901-2345-6789abcdef01",
            "qos": 2
        }
    ]
}

brokerUrl - (String) adres URL brokera MQTT w formacie tcp://host:port lub ssl://host:port
clientId - (String) unikalny identyfikator klienta MQTT
username - (String) nazwa użytkownika do autoryzacji (opcjonalne)
password - (String) hasło użytkownika do autoryzacji (opcjonalne)
mqttMessageList - (list) lista tematów MQTT do subskrypcji

Konfiguracja tematu MQTT:

topic - (String) nazwa tematu MQTT do subskrypcji (obsługuje wildcards MQTT: + i #)
targetUuid - (UUID) unikalny identyfikator parametru w systemie AMAGE, do którego będą mapowane dane z tego tematu
qos - (int) poziom jakości usługi QoS zgodnie ze standardem MQTT, domyślnie 1

Dostępne poziomy QoS: * 0 - At most once (co najwyżej raz) - najszybsze, ale możliwa utrata wiadomości * 1 - At least once (co najmniej raz) - domyślne, gwarantuje dostarczenie * 2 - Exactly once (dokładnie raz) - najwolniejsze, ale gwarantuje dostarczenie bez duplikatów

Moduł automatycznie obsługuje: * Nawiązywanie połączenia z brokerem MQTT * Autoryzację użytkownika (jeśli skonfigurowana) * Subskrypcję tematów z odpowiednim poziomem QoS * Automatyczne ponowne łączenie w przypadku utraty połączenia * Przekazywanie otrzymanych wiadomości do systemu AMAGE

Wyjściowa wtyczka - MQTT

Nazwa modułu: mqtt

Mechanizm wysyłania danych do brokera MQTT. Moduł nawiązuje połączenie z brokerem MQTT i publikuje otrzymane dane parametrów w postaci wiadomości MQTT na odpowiednich tematach.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/output/mqtt/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca docelowy broker MQTT).

{
    "brokerUrl": "tcp://mqtt.example.com:1883",
    "clientId": "amage-pvd-publisher",
    "rootTopic": "amage/sensors"
}

brokerUrl - (String) adres URL brokera MQTT w formacie tcp://host:port lub ssl://host:port
clientId - (String) unikalny identyfikator klienta MQTT
rootTopic - (String) główny temat MQTT, do którego będą publikowane dane

Format publikowanych tematów:

{rootTopic}/{parameterUUID}

Przykład:

amage/sensors/f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7
amage/sensors/a2b3c4d5-e6f7-8901-2345-6789abcdef01

Właściwości publikowanych wiadomości: * QoS: 1 (at least once delivery) - gwarantuje dostarczenie wiadomości * Payload: wartość parametru w formacie tekstowym * Clean Session: true - nie zachowuje stanu sesji między połączeniami

Moduł automatycznie obsługuje: * Nawiązywanie połączenia z brokerem MQTT dla każdej operacji wysyłania * Publikację wiadomości z poziomem QoS 1 * Automatyczne rozłączanie po wysłaniu danych * Logowanie wszystkich operacji MQTT * Obsługę błędów połączenia i publikacji

Nadawca - Satel KD (DB)

Nazwa modułu: satel

Mechanizm pobierania zdarzeń z bazy danych systemu kontroli dostępu Satel KD. Moduł łączy się z bazą danych MySQL systemu Satel, monitoruje zdarzenia autoryzacji (kod 271) i przekazuje je do systemu AMAGE w formacie JSON.

Przykładowa ścieżka do pliku konfiguracyjnego: <user.home>/configs/input/satel/default.json (zamiast default dopuszczalna jest inna, własna nazwa, np. opisująca konkretną instalację Satel).

{
    "serverAddress": "192.168.1.100",
    "serverPort": 3306,
    "database": "satel_kd",
    "username": "satel_user",
    "password": "satel_password",
    "dbPoolSize": 10,
    "controllerMappings": [
        {
            "controllerName": "Wejście główne",
            "parameterUuid": "f01ec5fd-117c-4cbf-aed8-1ab6066bd4c7"
        },
        {
            "controllerName": "Parking",
            "parameterUuid": "a2b3c4d5-e6f7-8901-2345-6789abcdef01"
        }
    ]
}

serverAddress - (String) adres serwera bazy danych MySQL systemu Satel KD
serverPort - (int) port serwera MySQL, domyślnie 3306
database - (String) nazwa bazy danych Satel KD
username - (String) nazwa użytkownika do dostępu do bazy danych
password - (String) hasło użytkownika do bazy danych
dbPoolSize - (int) rozmiar puli połączeń do bazy danych, domyślnie 10
controllerMappings - (list) lista mapowań kontrolerów na parametry w systemie AMAGE

Konfiguracja mapowania kontrolera:

controllerName - (String) nazwa kontrolera w systemie Satel KD (obsługuje częściowe dopasowanie)
parameterUuid - (UUID) unikalny identyfikator parametru w systemie AMAGE

Format danych JSON przekazywanych do systemu:

{
    "timestamp": "2025-01-24T10:30:15",
    "code": 271,
    "userId": "123456",
    "userName": "Jan Kowalski",
    "headerId": "1",
    "headerName": "Centrala główna",
    "controllerAddress": "192.168.1.10",
    "controllerName": "Wejście główne",
    "entryZoneName": "Strefa A"
}

Moduł automatycznie obsługuje:

Monitorowanie zdarzeń autoryzacji (kod 271) co 10 sekund
Aktualizację listy kontrolerów co 1 minutę
Zapamiętywanie ostatniego przetworzonego zdarzenia (unika duplikatów)
Połączenie z bazą danych przez pulę połączeń HikariCP
Filtrowanie zdarzeń tylko dla skonfigurowanych kontrolerów
Serializację zdarzeń do formatu JSON

Tabele bazy danych Satel KD:

event - tabela zdarzeń (główne źródło danych)
Kontroler - tabela kontrolerów (do aktualizacji listy urządzeń)

Moduł pobiera tylko zdarzenia autoryzacji (kod 271). Inne typy zdarzeń są ignorowane.