Plik konfiguracyjny programu ibvunit

Program ibvunit działa na podstawie pliku konfiguracyjnego. Plik jest typu xml.

Poniżej przedstawiono zawartość przykładowego pliku konfiguracyjnego programu ibvunit. Przykład ten zawiera również komentarze, które pełnią funkcję skróconej dokumentacji, podpowiedzi lub przykładu alternatywnej konfiguracji, dzięki temu jest możliwa edycja przekładowego pliku konfiguracyjnego ibvunit w sposób intuicyjny.

ibvunit.xml

<?xml version="1.0" encoding="UTF-8"?>
<Config xmlns="http://www.insbud.net/ibvunit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="1.11" xsi:schemaLocation="http://www.insbud.net/ibvunit ibvunit.xsd">
   <Modbus>
      <Gateways>
 
         <SerialPort Id="0" PortName="/dev/ttyS1" SleepMS="20" Parameters="9600/8-N-1"/>
         <SerialPort Id="1" PortName="/dev/ttyS2" SleepMS="20" Parameters="9600/8-N-1"/>
 
         <!-- 
              optional attribute serial port Parameters looks like "XXXX/D-P-S". default value "9600/8-N-1"
              XXXX - baud rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400)
              D - data bits - only 8 is supported
              P - parity flag (N - none, E - even, O - odd, M - mark, S - space)
              S - stop bits (1, 1.5, 2) 
         -->
         <!-- <SerialPort Id="0" PortName="COM4" SleepMS="0" Parameters="9600/8-N-1.5"/> -->
         <!-- <SerialPort Id="1" PortName="/dev/ttyS1" SleepMS="0" Parameters="19200/8-E-2"/> -->
         <!-- <SerialPort Id="1" PortName="/dev/ttyUSB0" SleepMS="0"/> -->
         <!-- <TcpRsConverter Id="0" IPAddress="192.168.200.50" Port="20108" SleepMS="35" /> -->
         <!-- <TlsPskListener Id="0" Port="50001" SleepMS="0" Psk="0102030405" PskIdentity="client" TimeoutMS="3000" CheckPeriodMS="10000"/> -->
      </Gateways>
 
      <!-- ConfigDir - path to the local directory that contains device configuration files -->
      <!-- RemoteConfigDir - url to the remote http directory from which ibvunit downloads configuration files if 
                           not found in local directory. if this attribute is not present or present and is empty
                           then ibvunit not handles downloading file (remember about terminating "/" and trailing "http://")-->
      <Devices ConfigDir="/ibsystem/ibvunit/devcfg" RemoteConfigDir="http://update.ibsystem.org/devcfg/1.2/">
 
         <Device GatewayId="0" Address="0" TimeoutMS="3000" />
 
         <!-- MaxDataWordsInFrame - 1 data word equals 1 modbus register or 8 modbus coils-->
         <!-- MaxRetransmissions - maximum number of retransmission in single transaction, default no retransmissions-->
         <Device GatewayId="1" Address="1" HardwareId="1000" FirmwareId="1" FirmwareVersion="0" MaxDataWordsInFrame="2" MaxRetransmissions="3"/>
      </Devices>
 
   </Modbus>
 
   <License Path="/ibsystem/license/license.dat" SignaturePublicKeyPath="" />
 
   <IbProtocol TcpPort="2001" SecureConnection="false" />
 
   <!-- Levels: TraceLo, Trace, TraceHi, DebugLo, Debug, DebugHi, Info, Notice, Warning, Error, Critical -->
   <!-- Types: Console, File, None -->
   <Log Type="File" Level="Info" Params="/ibsystem/ibvunit/ibvunit.log" MaxLogFileSize="10000000" MaxLogArchives="10" />
 
   <MWT Value="70"/>
   <EDT Value="IyMjIz4jIz4jIzMjIykjIykjIxMT" />
</Config>

Głównym elementem pliku konfiguracyjnego jest Config, posiadający między innymi atrybut Version, będący wersją pliku konfiguracyjnego. Właściwą wersją pliku konfiguracyjnego jest wersja 1.11 (dla programu ibvunit w wersji 2.3.5).

Jeżeli wersja ta nie będzie się zgadzała z numerem wersji aktualnie obsługiwanym przez program, wówczas zostanie zgłoszony błąd i program zakończy działanie. Błąd zostanie zgłoszony w terminalu, ponieważ parametry logów programu są zawarte w pliku konfiguracyjnym, który nie jest wspierany.

Pozostałe elementy pliku konfiguracyjnego zostały opisane w osobnych rozdziałach dokumentacji.

Element obowiązkowy. Zawiera w sobie inne elementy definiujące wszystkie urządzenia i bramki z protokołem MODBUS RTU.

Element obowiązkowy znajdujący się w elemencie <Modbus>. Element jest odpowiedzialna za zdefiniowanie wszystkich bramek za pośrednictwem których program ibvunit będzie się komunikował z urządzeniami docelowymi używając protokołu MODBUS RTU.

Program ibvunit wspiera następujące rodzaje bramek:

• lokalny port szeregowy (SerialPort)
• konwerter TCP/RS (TcpRsConverter)
• serwery TLS (TlsPskListener) - w tym wypadku za nawiązanie i podtrzymanie komunikacji odpowiedzialne są zewnętrzne urządzenia - np M1F1

Każda zdefiniowana bramka posiada atrybut Id, jest to unikalny identyfikator dla danej bramki. Musi być on unikalny w ramach całego elementu Gateways. Niedopuszczalne jest nadanie jednakowego identyfikatora np. dla jednej bramki będącej konwerterem TCP/RS i drugiej będącej lokalnym portem szeregowym.

Każda bramka musi być skorelowana przynajmniej z jednym urządzeniem. Jeżeli jakaś bramka zostanie zdefiniowana i nie zostanie z nią połączone żadne urządzenie z elementu <Devices> wówczas zostanie zgłoszony błąd i program zakończy działanie.

<SerialPort Id="1" PortName="COM6" Parameters="115200/8-N-1" SleepMS="0"/>

Powyższy element definiuje bramkę będącą portem szeregowym w systemie Windows o identyfikatorze „1”, oraz odwołuje się się do się do fizycznego portu „COM6”.

Element zawiera atrybuty:

• Id - (obowiązkowy) jest to unikalny identyfikator dla danej bramki. Musi być on unikalny w ramach całego elementu Gateways.
• PortName - (obowiązkowy) jest nazwą portu szeregowego w systemie na jakim jest uruchamiany program ibvunit.
  • Dla systemu Windows, nazwy portów szeregowych zazwyczaj mają postać „COM1”, „COM2”, „COM3” itd.
  • Dla systemu Linux, nazwy portów szeregowych zazwyczaj mają postać:
    • dla portów sprzętowych: „/dev/ttyS0”, „/dev/ttyS1” itd.
    • dla portów podłączanych przez port USB (konwerter USB/RS): „/dev/ttyUSB0”, „/dev/ttyUSB1” itd.
• Parameters - (obowiązkowy) definiuje parametry transmisji szeregowej. Jeżeli atrybut Parameters nie został jawnie zdefiniowany to otrzymuje on domyślną wartość „9600/8-N-1”. Konfiguracja ta powinna odpowiadać parametrom komunikacyjnym fizycznych urządzeń podłączonych do tej konkretnej bramki. Wartość atrybutu Parameters ma postać „XXXX/D-P-S” i oznacza:
  • XXXX - baud rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400)
  • D - data bits – wspierane jest tylko 8 bit
  • P - parity flag (N - none, E - even, O - odd, M - mark, S – space)
  • S - stop bits (1, 1.5, 2)
• SleepMS - (opcjonalny) określa minimalną przerwę pomiędzy kolejnymi transakcjami na danej bramce. jeżeli klient odpytuję zbyt często daną bramkę, zostanie wówczas wprowadzone sztuczne opóźnienie. Wartość jest podawana w milisekundach.

<TcpRsConverter Id="2" IPAddress="192.168.1.223" Port="20108" SleepMS="0"/>

Powyższy przykład definiuje konwerter RS485-ETHERNET o identyfikatorze 2, która posiada adres IP 192.168.1.223, oraz nasłuchuje na porcie TCP 20108. Parametry transmisji szeregowej są definiowane bezpośrednio w konfiguracji konwertera RS485-ETHERNET.

Element zawiera atrybuty:

• Id - (obowiązkowy) jest to unikalny identyfikator dla danej bramki. Musi być on unikalny w ramach całego elementu Gateways.
• IPAddress - (obowiązkowy) adres IP konwertera RS485-ETHERNET
• Port - (obowiązkowy) porcie TCP na którym nasłuchuje konwerter RS485-ETHERNET
• SleepMS - (opcjonalny) określa minimalną przerwę pomiędzy kolejnymi transakcjami na danej bramce. jeżeli klient odpytuję zbyt często daną bramkę, zostanie wówczas wprowadzone sztuczne opóźnienie. Wartość jest podawana w milisekundach.

<TlsPskListener Id="2" Port="2003" SleepMS="0" Psk="0102030405" PskIdentity="client" TimeoutMS="3000" CheckPeriodMS="10000"/>

Powyższy przykład definiuje bramkę typu serwer TLS. W tym przypadku program ibvunit uruchamia serwer TLS na wskazanym porcie.

Element zawiera atrybuty:

• Id - (obowiązkowy) jest to unikalny identyfikator dla danej bramki. Musi być on unikalny w ramach całego elementu Gateways.
• Port - (obowiązkowy) na tym porcie ibvunit będzie nasłuchiwał komunikacji TLS
• SleepMS - (opcjonalny) określa minimalną przerwę pomiędzy kolejnymi transakcjami na danej bramce. jeżeli klient odpytuję zbyt często daną bramkę, zostanie wówczas wprowadzone sztuczne opóźnienie. Wartość jest podawana w milisekundach.
• Psk - (pre shared key) musi być łańcuchem znakowym zawierającym tylko i wyłącznie litery i cyfry wchodzące w skład liczb heksadecymalnych (0-9a-fA-F). Jego długość powinna być liczbą parzystą mniejszą

bądź równą 512.

• PskIdentity - (pre shared key identity) może być łańcuchem znakowym do 128 znaków.
• TimeoutMS - określa czas, przez jaki program ibvunit będzie oczekiwał na odpowiedź po wysłaniu zapytania MODBUS do urządzenia, z którym komunikuje się przez tę bramkę.
• CheckPeriodMS - określa częstotliwość, z jaką program ibvunit ma monitorować stan połączenia z urządzeniem zdalnym (np. M1F1). Jeśli okres ciszy w komunikacji przekroczy tę wartość, nastąpi próba wymiany komunikatów. W przypadku niepowodzenia tej próby, dojdzie do rozłączenia z danym urządzeniem.

Wartości atrybutów Psk, PskIdentity, Port oraz adres IP/DNS maszyny na której uruchomiony jest program ibvunit muszą być wpisane w odpowiednie miejsca w urządzeniu M1F1, gdyż to właśnie one nawiązują oraz podtrzymują komunikację z daną bramką TLS ibvunita.

<Devices ConfigDir="/ibsystem/ibvunit/devcfg" RemoteConfigDir="http://update.ibsystem.org/devcfg/1.2/">
   <!-- multiple <Device/> elements -->
</Devices>

Element obowiązkowy znajdujący się w elemencie <Modbus>. Element jest odpowiedzialna za zdefiniowanie wszystkich urządzeń z komunikacją MODBUS RTU, które są podłączone do wcześniej zdefiniowanych bramek.

Element może zawierać wiele elementów <Device>.

Element zawiera atrybuty:

• ConfigDir - (obowiązkowy) to ścieżka do katalogu, w którym umieszczone są pliki konfiguracyjne urządzeń MODBUS. Ścieżka powinna mieć składnię odpowiednią dla danego systemu operacyjnego. Po uruchomieniu program ibvunit, każdy plik konfiguracji urządzenia MODBUS znajdujący się w tym katalogu jest parsowany najpierw pod kątem składni, a następnie pod kątem zawartości. Jeżeli prasowanie pojedynczego pliku konfiguracji urządzenia MODBUS zakończy się pomyślnie, wówczas zostaje on wczytany jako konfiguracja danego urządzenia. Dzięki temu, program ibvunit będzie w stanie rozpoznać mapę rejestrów danego urządzenia oraz dokonać ich walidacji, podczas przetwarzania komendy operującej na wartościach rejestrów w fizycznym urządzeniu. Dodanie obsługi nowego urządzenia polega na wgraniu do tego katalogu odpowiedniego pliku konfiguracyjnego, bez konieczności zmiany kodu źródłowego aplikacji.
• RemoteConfigDir - (obowiązkowy) adres z którego ibvunit spróbuje pobrać konfiguracje urządzenia jeżeli nie zostanie znaleziona w lokalnym katalogu ConfigDir

Z wszystkimi urządzeniami wymienionymi w elemencie Devices, którym jawnie nie nadano atrybutów HardwareId, FirmwareId oraz FirmwareVersion, nawiązywana jest komunikacja podczas startu programu ibvunit, w celu ich identyfikacji (id urządzenia oraz numer wersji). Na tej podstawie, ibvunit przydziela danemu urządzeniu konfigurację, wybierając ją z odpowiedniego pliku xml. Jeżeli dany plik nie zostanie znaleziony w lokalnym katalogu, wówczas aplikacja usiłuje go pobrać ze zdalnej lokalizacji, która jest podana w atrybucie RemoteConfigDir elementu Devices.

Element obowiązkowy znajdujący się w elemencie <Devices>. Element jest odpowiedzialna za zdefiniowanie pojedynczego urządzenia z komunikacją MODBUS RTU.

<Device GatewayId="0" Address="255" HardwareId="3" FirmwareId="1" FirmwareVersion="6" TimeoutMS="5000" MaxDataWordsInFrame="2" MaxRetransmissions="2"/>

Element zawiera atrybuty:

• GatewayId - (obowiązkowy) identyfikator bramki, do której jest podłączone urządzenie. Bramka o takim identyfikatorze musi być wcześniej zdefiniowana w elemencie <Gateways>. W przeciwnym wypadku zostanie zgłoszony błąd i program zakończy działanie.
• Address - (obowiązkowy) identyfikator urządzenia. Musi być unikalny w ramach wszystkich urządzeń podłączonych do danej bramki.
• HardwareId, FirmwareId, FirmwareVersion - (opcjonalne) Dla urządzeń dedykowanych dla IB-System, nie ma potrzeby definiowania tych atrybutów. Urządzenie zostanie automatycznie wykryte a odpowiedni plik konfiguracyjny urządzenia zostanie poprany i wczytany. Jeżeli zostały podane, ibvunit nie będzie uruchamiała mechanizmu wykrywania typu danego urządzenia a zostanie wczytany plik konfiguracyjny dla zdefionowanego przez te atrybuty urządzenia. Skrótowo urządzenia definiowane są przez ciąg o postaci: HxFyVz co oznacza przypisanie wartości atrybutów HardwareId=„x” FirmwareId=„y” FirmwareVersion=„z”
• TimeoutMS - (opcjonalny) określa maksymalny czas wyrażony w milisekundach przez jaki program ibvunit będzie czekał na odpowiedź z danego urządzenia. Jeżeli przez ten czas odpytane urządzenie nie odpowie, system zinterpretuje ten fakt jako błąd komunikacji z urządzeniem. Wartość tą należy dobierać empirycznie w zależności od prędkości komunikacji, topologii oraz długości magistrali komunikacyjnej RS.
• MaxDataWordsInFrame - (opcjonalny) Definiuje maksymalną liczbę rejestrów lub coili, które ibvunit przekazuje lub nakazuje przekazać urządzeniu slave w jednej transakcji. W przypadku rejestrów, liczba ta jest bezpośrednia, natomiast w przypadku coili, powinna być pomnożona przez 8 (tyle coili mieści się w jednym bajcie). W podanym przykładzie, ibvunit przekaże maksymalnie 2 rejestry lub 16 coili w funkcjach zapisu/odczytu rejestrów/coili. Jeśli ten atrybut nie jest podany, nie ma ograniczenia co do liczby przekazywanych rejestrów/coili - jedynym ograniczeniem jest format odpowiedniej funkcji MODBUS. Parametr ten może być przydatny dla urządzeń podłączonych w magistrali, w której występują zakłócenia lub urządzenie nie jest zdolne obsługi długich zapytań/odpowiedzi.
• MaxRetransmissions - (opcjonalny) umożliwia retransmisję pakietu w przypadku nieudanej transakcji, określając liczbę tych retransmisji. Domyślna wartość tego atrybutu wynosi 0, co oznacza, że ibvunit natychmiast zwraca błąd w momencie jego wystąpienia. W podanym przykładzie, ibvunit spróbuje jeszcze dwa razy nawiązać połączenie z urządzeniem zanim zgłosi błąd.

<License Path="/ibsystem/license/license.dat" SignaturePublicKeyPath="" />

Element obowiązkowy wskazuje na dostarczony plik licencji. Bez ważnego pliku licencji aplikacja nie uruchomi się.

Element zawiera atrybuty:

• Path - ścieżka gdzie znajduje się dostarczony plik licencji (license.dat)
• SignaturePublicKeyPath

<IbProtocol TcpPort="2001" SecureConnection="false" />

Element IbProtocol opisuje parametry protokołu, przy pomocy którego, zewnętrzne programy mogą się komunikować z programem ibvunit.

Element zawiera atrybuty:

• TcpPort - adres portu TCP, na którym nasłuchuje serwer ibprotokołu
• SecureConnection - atrybut typu bool, mówi czy serwer ibprotokołu będzie wykorzystywał bezpieczną komunikację SSL. Jeżeli tak, wówczas użyje on klucza PEM key.pem, lokalnego certyfikatu ibpakietu (local.cert.pem) oraz lokalnego certyfikatu instytucji certyfikującej (local.ca.cert.pem). Wszystkie te pliki powinny się znajdować w katalogu licencji.

<Log Type="File" Level="Info" Params="/ibsystem/ibvunit/ibvunit.log" MaxLogFileSize="40000000" MaxLogArchives="20" />

Element odpowiedzialny za konfigurację systemu logowania programu ibvunit.

Element zawiera atrybuty:

• Type - oznacza określenie ujścia dla logów i może przyjmować wartości:
  • Console – logi wyświetlane jedynie na konsoli
  • File - logi zapisywane do pliku
  • None - wyłączenie logowania
• Level - oznacza poziom logowania i może przyjmować wartości:
  • TraceLo - najwięcej szczegółów
  • Trace
  • TraceHi
  • DebugLo
  • Debug
  • DebugHi
  • Info
  • Notice
  • Warning
  • Error
  • Critical – najmniej szczegółów
• Params - określa plik gdzie znajduje się plik logów a jeżeli go nie ma to gdzie ma zostać utworzony. Ścieżka powinna mieć składnię odpowiednią dla danego systemu operacyjnego.
• MaxLogFileSize - (opcjonalny) posiada wartość domyślną równą 10*1024*1024 i określa maksymalny rozmiar pojedynczego pliku logów. Ze względów wydajnościowych i po części praktycznych, rozmiar pojedynczego pliku jest większy od tej wartości z dokładnością do rozmiaru zalogowanej linii (tak aby zakończyć logowanie pełnej linii) oraz do 5 sekund.
• MaxLogArchives - (opcjonalny) posiada wartość domyślną równą 10 co oznacza że że oprócz bieżącego pliku logów, może się znaleźć do 10 archiwalnych plików. Pliki archiwalne tworzone są przez dodanie do nazwy pliku logu sufiksu .N gdzie N jest indeksem numerowanym od 0. 0 oznacza najnowsze archiwum, im wyższy numer tym starsze. Najstarsze pliki archiwalne są usuwane, jeżeli ich liczba przekroczy wartość tego atrybutu.

W przykładowej definicji elementu <Log>, mechanizm rotacji logów zakłada istnienie do 20 plików archiwalnych. Zarówno archiwalne jak i bieżące będą mogły mieć rozmiar do ok. 40MB.

<MWT Value="70"/>

Wartość atrybutu Value oznacza maksymalną ilość dni pracy programu ibvunit. Po tym okresie program zostanie zablokowany, zamknięty i niemożliwe będzie jej ponowne uruchomienie.

Funkcjonalność ta została wprowadzona dla osób i firm wykorzystujących IB-System w celach komercyjnych do dalszej odsprzedaży i ma za zadanie wyłączenie części funkcjonalności w przypadku przekroczenia np. okresu testowego.

Jest to funkcjonalność stosunkowo prymitywna i znajomość IB-System od strony funkcjonalności i konfiguracji umożliwi zdjęcie takiej blokady, niemniej może być użyteczna w przypadku sprzedaży gotowych systemów z gotowym i skonfigurowanym IB-System jako produkt testowy.

Element MWT jest opcjonalny. Jeżeli nie występuje w pliku konfiguracji oznacza, że ograniczenie czasu pracy programu ibvunit nie istnieje.

Jeżeli element został zdefiniowany, w katalogu z plikiem wykonawczym ibvunit jest tworzony plik *.bin, który jest aktualizowany wraz z upłynięciem odpowiedniego odcinka czasowego. Podczas uruchomienia programu ibvunit czas ten jest odczytywany z w/w pliku.

Aby usunąć ograniczenie czasu pracy programu ibvunit, należy usunąć element MWT z pliku konfiguracyjnego programu, zatrzymać program ibvunit, usunąć plik *.bin i dopiero ponownie uruchomić program ibvunit.

<EDT Value="IyMjIz4jIz4jIzMjIykjIykjIxMT" />

Element ten konfiguruje podobną funkcjonalność co element MWT przy czym wartość atrybutu Value oznacza zakodowaną datę, po której program ibvunit ma zostać zablokowana.

Aktualna data jest datą systemową, dlatego zmiana daty systemowej lub uruchomienie programu ibvunit na systemach bez sprzętowego zegara czasu rzeczywistego (RTC) może powodować obejście tego zabezpieczenia.

Element ten jest obowiązkowy, przy czym jeżeli atrybut Value przyjmie wartość „IyMjIz4jIz4jIzMjIykjIykjIxMT” oznacza dezaktywację zabezpieczenia EDT.