====== Plik konfiguracyjny programu ibvunit ======

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

===== Przykładowy plik konfiguracyjny =====

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.

<code xml 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>
</code>

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.

===== <Modbus> =====

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

==== <Gateways> ====

Element obowiązkowy znajdujący się w elemencie [[pl:ibvunit:ibvunit-config#<Modbus>|<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 [[pl:ibvunit:ibvunit-config#<Devices>|<Devices>]] wówczas zostanie zgłoszony błąd i program zakończy działanie.

=== Lokalny port szeregowy (SerialPort) ===

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

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.

=== konwerter TCP/RS (TcpRsConverter) ===

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

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.

=== serwer TLS (TlsPskListener) ===

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

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> ====

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

Element obowiązkowy znajdujący się w elemencie [[pl:ibvunit:ibvunit-config#<Modbus>|<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 [[pl:ibvunit:ibvunit-config#<Device>|<Device>]].

Element zawiera atrybuty:

  * **ConfigDir** - (obowiązkowy) to ścieżka do katalogu, w którym umieszczone są [[pl:ibvunit:ibvunit-dev-modbus-rtu-config|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**.

=== <Device> ===

Element obowiązkowy znajdujący się w elemencie [[pl:ibvunit:ibvunit-config#<Devices>|<Devices>]]. Element jest odpowiedzialna za zdefiniowanie pojedynczego urządzenia z komunikacją MODBUS RTU. 

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

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 [[pl:ibvunit:ibvunit-config#<Gateways>|<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 [[pl:ibvunit:ibvunit-dev-modbus-rtu-config|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> =====

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

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> =====

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

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 [[pl:ibprotocol:start|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 [[pl:ibvunit:ibvunit-config#<License>|licencji]].

===== <Log> =====

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

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> =====

<code xml>
<MWT Value="70"/>
</code>

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> =====

<code xml>
<EDT Value="IyMjIz4jIz4jIzMjIykjIykjIxMT" />
</code>

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**.