The ibvunit program operates based on a configuration file. The file is of xml type.

Below is the content of a sample configuration file for the ibvunit program. This example also includes comments, which serve as a brief documentation, hints, or an example of alternative configuration, making it possible to edit the sample ibvunit configuration file intuitively.

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>

The main element of the configuration file is Config, which among other things, has the Version attribute, which is the version of the configuration file. The correct version of the configuration file is version 1.11 (for the ibvunit program in version 2.3.5).

If this version does not match the version number currently handled by the program, an error will be reported and the program will stop running. The error will be reported in the terminal, as the program's log parameters are contained in the configuration file, which is not supported.

The other elements of the configuration file have been described in separate chapters of the documentation.

A mandatory element. It contains other elements that define all devices and gateways with the MODBUS RTU protocol.

A mandatory element located in the <Modbus> element. The element is responsible for defining all gateways through which the ibvunit program will communicate with target devices using the MODBUS RTU protocol.

The ibvunit program supports the following types of gateways:

• local serial port (SerialPort)
• TCP/RS converter (TcpRsConverter)
• TLS servers (TlsPskListener) - in this case, the establishment and maintenance of communication is the responsibility of external devices - e.g., M1F1

Each defined gateway has an Id attribute, it is a unique identifier for a given gateway. It must be unique within the entire Gateways element. It is not allowed to assign the same identifier, for example, for one gateway being a TCP/RS converter and another being a local serial port.

Each gateway must be correlated with at least one device. If a gateway is defined and no device from the <Devices> element is connected with it, an error will be reported and the program will stop running.

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

The above element defines a gateway being a serial port in the Windows system with the identifier “1”, and refers to the physical port “COM6”.

The element contains attributes:

• Id - (mandatory) it is a unique identifier for a given gateway. It must be unique within the entire Gateways element.
• PortName - (mandatory) it is the name of the serial port in the system on which the ibvunit program is running.
  • For Windows, serial port names usually take the form “COM1”, “COM2”, “COM3” etc.
  • For Linux, serial port names usually take the form:
    • for hardware ports: “/dev/ttyS0”, “/dev/ttyS1” etc.
    • or ports connected via USB port (USB/RS converter): “/dev/ttyUSB0”, “/dev/ttyUSB1” etc.
• Parameters - (mandatory) defines serial transmission parameters. If the Parameters attribute is not explicitly defined, it receives the default value “9600/8-N-1”. This configuration should match the communication parameters of physical devices connected to this specific gateway. The value of the Parameters attribute takes the form “XXXX/D-P-S” and means:
  • XXXX - baud rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400)
  • D - data bits – only 8 bits are supported
  • P - parity flag (N - none, E - even, O - odd, M - mark, S – space)
  • S - stop bits (1, 1.5, 2)
• SleepMS - (optional) specifies the minimum delay between successive transactions on a given gateway. If a client queries a given gateway too often, a artificial delay will be introduced. The value is given in milliseconds.

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

The above example defines an RS485-ETHERNET converter with the identifier 2, which has the IP address 192.168.1.223, and listens on TCP port 20108. The serial transmission parameters are defined directly in the RS485-ETHERNET converter configuration.

The element contains the following attributes:

• Id - (mandatory) this is a unique identifier for a given gateway. It must be unique within the entire Gateways element.
• IPAddress - (mandatory) the IP address of the RS485-ETHERNET converter
• Port - (mandatory) the TCP port on which the RS485-ETHERNET converter listens
• SleepMS - (optional) defines the minimum delay between subsequent transactions on a given gateway. If a client queries a gateway too frequently, an artificial delay will be introduced. The value is given in milliseconds.

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

The above example defines a TLS server type gateway. In this case, the ibvunit program runs a TLS server on the indicated port.

The element contains the following attributes:

• Id - (mandatory) this is a unique identifier for a given gateway. It must be unique within the entire Gateways element.
• Port - (mandatory) on this port, ibvunit will listen for TLS communication.
• SleepMS - (optional) defines the minimum delay between subsequent transactions on a given gateway. If a client queries a gateway too frequently, an artificial delay will be introduced. The value is given in milliseconds.
• Psk - (pre-shared key) must be a string containing only letters and numbers that are part of hexadecimal numbers (0-9a-fA-F). Its length should be an even number less than or equal to 512.
• PskIdentity - (pre-shared key identity) can be a string up to 128 characters.
• TimeoutMS - defines the time during which the ibvunit program will wait for a response after sending a MODBUS query to the device communicating through this gateway.
• CheckPeriodMS - defines the frequency at which the ibvunit program is to monitor the connection status with the remote device (e.g., M1F1). If the period of silence in communication exceeds this value, an attempt will be made to exchange messages. In case of failure of this attempt, the connection with the device will be disconnected.

The values of the Psk, PskIdentity, Port, and the IP/DNS address of the machine on which the ibvunit program is running must be entered in the appropriate places in the M1F1 device, as they are the ones that establish and maintain communication with the given TLS gateway of ibvunit.

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

This is a mandatory element located in the <Devices> element. This element is responsible for defining a single device with MODBUS RTU communication.

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

The element contains the following attributes:

• GatewayId - (mandatory) the identifier of the gateway to which the device is connected. A gateway with such an identifier must be previously defined in the <Gateways> element. Otherwise, an error will be reported and the program will terminate.
• Address - (mandatory) the identifier of the device. It must be unique among all devices connected to a given gateway.
• HardwareId, FirmwareId, FirmwareVersion - (optional) For devices dedicated to the IB-System, there is no need to define these attributes. The device will be automatically detected and the appropriate device configuration file will be downloaded and loaded. If they are provided, ibvunit will not run the device type detection mechanism and will load the configuration file for the device defined by these attributes. Briefly, devices are defined by a string in the form: HxFyVz which means assigning the values of the attributes HardwareId=“x” FirmwareId=“y” FirmwareVersion=“z”
• TimeoutMS - (optional) determines the maximum time in milliseconds for which the ibvunit program will wait for a response from a given device. If the queried device does not respond within this time, the system will interpret this fact as a communication error with the device. This value should be determined empirically, depending on the speed of communication, topology, and length of the RS communication bus.
• MaxDataWordsInFrame - (optional) Defines the maximum number of registers or coils that ibvunit transmits or commands the slave device to transmit in one transaction. In the case of registers, this number is direct, while in the case of coils, it should be multiplied by 8 (that's how many coils are in one byte). In the given example, ibvunit will transmit a maximum of 2 registers or 16 coils in read/write register/coil functions. If this attribute is not given, there is no limit to the number of registers/coils being transferred - the only limit is the format of the appropriate MODBUS function. This parameter may be useful for devices connected to a bus where there are disturbances or the device is not capable of handling long queries/responses.
• MaxRetransmissions - (optional) allows for packet retransmission in the event of a failed transaction, specifying the number of these retransmissions. The default value of this attribute is 0, which means that ibvunit immediately returns an error when it occurs. In the given example, ibvunit will try two more times to establish a connection with the device before reporting an error.

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

Mandatory element pointing to the provided license file. Without a valid license file, the program will not start.

The element contains the attributes:

• Path - path where the provided license file (license.dat) is located.
• SignaturePublicKeyPath

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

The IbProtocol element describes the parameters of the protocol, with which, external programs can communicate with the ibvunit program.

The element contains attributes:

• TcpPort - TCP port address on which the ibprotocol server listens
• SecureConnection - a bool type attribute, it says whether the ibprotocol server will use secure SSL communication. If so, it will use the PEM key.pem, local ibpackage certificate (local.cert.pem) and local certifying institution certificate (local.ca.cert.pem). All these files should be located in the license directory.

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

Element responsible for configuring the logging system of the ibvunit program.

The element contains the attributes:

• Type - indicates the outlet for the logs and can take values:
  • Console – logs are displayed only on the console
  • File - logs are saved to a file
  • None - logging is disabled
• Level - indicates the logging level and can take values:
  • TraceLo - most details
  • Trace
  • TraceHi
  • DebugLo
  • Debug
  • DebugHi
  • Info
  • Notice
  • Warning
  • Error
  • Critical – least details
• Params - specifies the file where the log file is located and if it does not exist, where it should be created. The path should have syntax appropriate for the given operating system.
• MaxLogFileSize - (optional) has a default value equal to 10*1024*1024 and determines the maximum size of a single log file. For performance and practical reasons, the size of a single file is larger than this value with the accuracy of the size of the logged line (in order to finish logging a full line) and up to 5 seconds.
• MaxLogArchives - (optional) has a default value equal to 10, which means that in addition to the current log file, there may be up to 10 archival files. Archival files are created by adding a .N suffix to the log file name where N is an index numbered from 0. 0 means the newest archive, the higher the number, the older. The oldest archival files are removed if their number exceeds the value of this attribute.

In the sample definition of the <Log> element, the log rotation mechanism assumes the existence of up to 20 archival files. Both archival and current can be up to about 40MB in size.

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