====== Configuration file for the ibvunit program ======

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

===== Sample configuration file =====

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.

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

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.

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

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

==== <Gateways> ====

A mandatory element located in the [[en:ibvunit:ibvunit-config#<Modbus>|<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 [[en:ibvunit:ibvunit-config#<Devices>|<Devices>]] element is connected with it, an error will be reported and the program will stop running.

=== Local serial port (SerialPort) ===

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

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.

=== TCP/RS Converter (TcpRsConverter) ===

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

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.

=== TLS Server (TlsPskListener) ===

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

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

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

This is a mandatory element found within the [[en:ibvunit:ibvunit-config#<Modbus>|<Modbus>]] element. This element is responsible for defining all devices with MODBUS RTU communication that are connected to previously defined gateways.

The element can contain multiple [[en:ibvunit:ibvunit-config#<Device>|<Device>]] elements.

This element contains the attributes:

  * **ConfigDir** - (mandatory) This is the path to the directory where the [[en:ibvunit:ibvunit-dev-modbus-rtu-config|MODBUS device configuration files]] are located. The path should follow the syntax appropriate for the operating system. When the **ibvunit** program starts, each MODBUS device configuration file in this directory is parsed first for syntax, then for content. If parsing a single MODBUS device configuration file is successful, then it is loaded as the configuration for that device. As a result, the **ibvunit** program will be able to recognize the register map of that device and perform their validation when processing a command operating on register values in the physical device. Adding support for a new device involves uploading the appropriate configuration file to this directory without needing to change the application's source code.
  * **RemoteConfigDir** -  (mandatory) This is the address from which **ibvunit** will try to fetch the device configuration if it is not found in the local **ConfigDir** directory.

With all devices listed in the **Devices** element that have not explicitly been assigned the **HardwareId**, **FirmwareId** and **FirmwareVersion** attributes, communication is established during the **ibvunit** program startup in order to identify them (device id and version number). Based on this, **ibvunit** assigns a configuration to each device, selecting it from the appropriate xml file. If a given file is not found in the local directory, then the application tries to download it from the remote location specified in the **RemoteConfigDir** attribute of the **Devices** element.

=== <Device> ===

This is a mandatory element located in the [[en:ibvunit:ibvunit-config#<Devices>|<Devices>]] element. This element is responsible for defining a single device with MODBUS RTU communication.

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

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

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

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

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

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 [[en:ibprotocol:start|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 [[en:ibvunit:ibvunit-config#<License>|license]] directory.

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

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

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

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

The **Value** attribute represents the maximum number of days the **ibvunit** program can run. After this period, the program will be blocked, closed, and it will be impossible to restart it.

This feature has been introduced for individuals and companies using **IB-System** for commercial reselling purposes and is designed to disable some functionalities in case, for example, the trial period is exceeded.

This is a relatively primitive feature and familiarity with **IB-System** in terms of functionalities and configurations will allow for the removal of such a blockade, nevertheless, it can be useful when selling ready-made systems with a ready and configured **IB-System** as a trial product.

The **MWT** element is optional. If it does not appear in the configuration file, it means that the **ibvunit** program's operating time limit does not exist.

If the element has been defined, a *.bin file is created in the directory with the **ibvunit** executable file, which is updated as the appropriate time period elapses. When the **ibvunit** program is launched, this time is read from the aforementioned file.

To remove the operating time limit of the **ibvunit** program, you need to remove the **MWT** element from the program's configuration file, stop the **ibvunit** program, delete the *.bin file, and then restart the **ibvunit** program.

===== <EDT> =====

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

This element configures similar functionality to the **MWT** element, however, the **Value** attribute represents the encoded date after which the **ibvunit** program is to be blocked.

The current date is the system date, therefore changing the system date or running the **ibvunit** program on systems without a real-time clock (RTC) can bypass this security measure.

This element is mandatory, however, if the **Value** attribute takes the value "IyMjIz4jIz4jIzMjIykjIykjIxMT" it means the deactivation of the **EDT** security feature.