====== MODBUS RTU devices configuration file ======

Communication is established with all devices listed in the [[en:ibvunit:ibvunit-config#<Devices>|<Devices>]] element during the start of the **ibvunit** program.

Devices are identified based on three numerical values:

  * **HardwareId** (h) –  numerical hardware identifier for devices.
  * **FirmwareId** (f) – numerical firmware identifier.
  * **FirmwareVersion** (v) – numerical firmware version identifier.

Based on the above values, a unique device name is formed, for example, **h3f1v6**. Each device has its individual configuration file.

The **ibvunit** program assigns a configuration to a given device, selecting it from the appropriate xml file. The recommended name for the configuration file is the full name of the device, for example, **h3f1v6.xml**.

===== Example Configuration File =====

Below is the syntax of an example configuration file for the **h1021f1v0** device. This example also includes comments that serve as a brief documentation, hints, or an example of alternative configuration, thus making it possible to edit the configuration file intuitively.

<code xml h1021f1v0.xml>
<?xml version="1.0" encoding="UTF-8"?>
<!--Copyright (C) 2004-2015 InsBud www.insbud.net-->

<Device xmlns="http://www.insbud.net/common/devcfg" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.insbud.net/common/devcfg devcfg.xsd"
        Version="1.2"
        HardwareId="1021" 
        FirmwareId="1" 
        FirmwareVersion="0">

    <!-- 
        Airflow transmitter configuration file

        For ibvunit-2.0 application

        This configuration file was developed based on the register documentation provided by the manufacturer.

        Factory communication parameters: 4800 bps, 8 data bits, parity: NONE; 1 stop bit

        Default ID1. Possibility to change the ID from the protocol level and via jumpers on the device.

    -->
        
  <!-- <HoldingRegisters SetMode="Single"> -->
  <!-- <HoldingRegisters> -->
  <HoldingRegisters SetMode="Single">

    <!--
    content:        Current wind speed value
    access type:    R
    Definition:     /
    Unit:           [0.1 m/s] ze znakiem
    Remarks:        10 times the actual value
    -->
    <HReg Addr="0" Name="counter.current.wind.speed" Rd="1" Wr="0" Min="-32766" Max="32766" Presentation="signed"/>

    <!--
    content:        Integer value of current air volume (integer)
    access type:    R
    Definition:     /
    Unit:           [1 m³/h]
    Remarks:        Range 0~65535，Max 65535，exceed 65535 display 65535
                    Current air volume value = current wind speed value (in meters per second) x pipe cross-sectional area (in square centimeters) x 3600÷10000.
                    Example result: Integer value of air volume: 0221 H (hexadecimal)= 545=> integer value of air volume = 545m³/h
    -->
    <HReg Addr="1" Name="counter.current.air.volume.int" Rd="1" Wr="0" Min="0" Max="65535" Presentation="unsigned"/>

    <!--
    content:        The upper 16 digits of the floating-point value of the current air volume
    access type:    R
    Definition:     /
    Unit:           [m³/h]
    Remarks:        Current air volume value = current wind speed value (in meters per second) x pipe cross-sectional area (square centimeters) x 3600÷10000.
                    Floating-point data retains one significant decimal place.
                    Example result: Air volume floating point value: 44084CCD H (hexadecimal) = 545.2 => air volume floating point value = 545.2m³/h
    -->
    <HReg Addr="2" Name="counter.current.air.volume.float.h" Rd="1" Wr="0" Min="0" Max="65535" Presentation="unsigned"/>

    <!--
    content:        The lower 16 digits of the floating-point value of the current air volume
    access type:    R
    Definition:     /
    Unit:           [m³/h]
    Remarks:        /
    -->
    <HReg Addr="3" Name="counter.current.air.volume.float.l" Rd="1" Wr="0" Min="0" Max="65535" Presentation="unsigned"/>

    <!--
    content:        Current pipe cross-sectional area
    access type:    RW
    Definition:     /
    Unit:           [1 cm2 ]
    Remarks:        /
    -->
    <HReg Addr="512" Name="setting.duct.area" Rd="1" Wr="1" Min="0" Max="65535" Presentation="unsigned"/>

    <!--
    content:        Device Address
    access type:    RW
    Definition:     /
    Unit:           /
    Remarks:        1~254（default 1）
    -->
    <HReg Addr="2000" Name="modbus.address" Rd="1" Wr="1" Min="0" Max="254" Presentation="unsigned"/>

    <!--
    content:        Device baud rate
    access type:    RW
    Definition:     0 means 2400
                    1 means 4800
                    2 means 9600
                    3 means 19200
                    4 means 38400
                    5 means 57600
                    6 means 115200
                    7 means 1200
    Unit:           /
    Remarks:        /
    -->
    <HReg Addr="2001" Name="modbus.speed" Rd="1" Wr="1" Min="0" Max="7" Presentation="unsigned"/>

  </HoldingRegisters>

  <InputRegisters>
  </InputRegisters>
  
  <Coils>
  </Coils>
  
  <DiscreteInputs>
  </DiscreteInputs>

</Device>
</code>

The main element of the configuration file is **Device**, which among other things has attributes:

  * **Version** – determines the version of the device configuration file. The proper version of the device configuration file is 1.2 (for ibvunit program in version 2.3.5).
  * **HardwareId** (h) – numerical hardware identifier for devices
  * **FirmwareId** (f) – numerical firmware identifier
  * **FirmwareVersion** (v) – numerical firmware version identifier

The remaining elements of the configuration file are described in separate chapters of the documentation.

===== <HoldingRegisters> =====

<code>
<HoldingRegisters SetMode="Multiple">
  <!-- multiple <HReg/> elements -->
</HoldingRegisters>
</code>

The **HoldingRegisters** element is responsible for defining device registers of the **Holding Registers** type with MODBUS RTU communication, which will be available for the **ibvunit** program.

The element can contain multiple [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<HReg>|<HReg>]] elements or none at all.

The element contains the attributes:

  * **SetMode** - (mandatory) The attribute value determines whether to use the MODBUS PresetSingleRegister or WriteMultipleRegisters function to set the value of a given register. The attribute can take values:
    * **Multiple** - means that communication with the MODBUS device allows for bulk writes for Holding Registers. The **Multiple** value should only be set for MODBUS devices correctly implementing the WriteMultipleRegisters function (code 16).
    * **Single** - means that communication with the MODBUS device only allows for single writes for Holding Registers. The Single value should only be set for MODBUS devices correctly implementing the PresetSingleRegister function (code 6).

If the device supports both modes, it is recommended to use **Multiple** for performance reasons.

Each device supporting **HoldingRegister** type variables must correctly implement at least one of the above functions to change the value of a given register.

Reading **HoldingRegister** type variables is performed by the MODBUS ReadHoldingRegisters function (code 3), which must also be supported by the device.

==== <HReg>====

The element located in the [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<HoldingRegisters>|<HoldingRegisters>]] element. The element is responsible for defining a single register of the **Holding Registers** type with MODBUS RTU communication.

<code>
<HReg Addr="0" Name="dev.hardware" Rd="1" Wr="0" Min="0" Max="65535" Presentation="unsigned"/>
<HReg Addr="2" Name="reg.speed" Rd="1" Wr="1" Min="0x0055" Max="0x00aa" Presentation="hex"/>
</code>

The element contains the attributes:

  * **Addr** – the address of the register in a MODBUS RTU compatible device.
  * **Name** – the name of the register. Under this name, the register will function as a variable in the **ibvunit** program and throughout the **IB-System**. The name of the parameter is arbitrary, but it is assumed to be intuitive. Therefore, standardizing names according to the [[en:ibprotocol:start|ibprotocol]] documentation is recommended.
  * **Rd** – a flag (value 0 or 1) indicating whether the register can be read.
  * **Wr** – a flag (value 0 or 1) indicating whether the register can be written to.
  * **Min** – the minimum value for the register.
  * **Max** – the maximum value for the register.
  * **Presentation** – the way the variable is presented in the **ibvunit** program and throughout the **IB-System**. The permissible attribute values are:
    * **unsigned** – an unsigned integer value. Value range 0..65535.
    * **signed** – a signed integer value. Value range -32768..32767.
    * **hex** – a numerical value in hexadecimal 0x0000. Value range 0x0000..0xffff 
  * **SwappBytes** -  (optional) If it's defined and its value is "1", then **ibvunit** switches two bytes of the given register's value, during transmission to and from the device. By default, bytes are not swapped and are transferred according to the MODBUS RTU protocol standard (SwappBytes="0").

===== <InputRegisters> =====

<code>
<InputRegisters>
  <!-- multiple <IReg/> elements -->
</InputRegisters>
</code>

The element **InputRegisters** is responsible for defining the device's **Input Registers** with MODBUS RTU communication, which will be available for the **ibvunit** program.

The element can contain multiple [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<IReg>|<IReg>]] elements or not contain any such element.

Each device supporting **InputRegister** type variables must correctly implement the MODBUS ReadInputRegisters function (code 4) in order to read the value of a given input register.

**InputRegister** type registers are read-only.

==== <IReg>====

An element located in the [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<InputRegisters>|<InputRegisters>]] element. The element is responsible for defining a single **Input Registers** device register with MODBUS RTU communication.

<code>
<IReg Addr="0" Name="counter.ht2.tm" Presentation="signed"/>
</code>

The element contains attributes:

  * **Addr** – the address of the register in a MODBUS RTU compatible device.
  * **Name** – the name of the register. Under this name, the register will function as a variable in the **ibvunit** program and throughout the **IB-System**. The name of the parameter is arbitrary, but it is assumed to be intuitive. Therefore, standardizing names according to the [[en:ibprotocol:start|ibprotocol]] documentation is recommended.
  * **Presentation** – the way the variable is presented in the **ibvunit** program and throughout the **IB-System**. The permissible attribute values are:
    * **unsigned** – an unsigned integer value. Value range 0..65535.
    * **signed** – a signed integer value. Value range -32768..32767.
    * **hex** – a numerical value in hexadecimal 0x0000. Value range 0x0000..0xffff 
  * **SwappBytes** -  (optional) If it's defined and its value is "1", then **ibvunit** switches two bytes of the given register's value, during transmission to and from the device. By default, bytes are not swapped and are transferred according to the MODBUS RTU protocol standard (SwappBytes="0").

===== <Coils> =====

<code>
<CoilsSetMode="Multiple">
  <!-- multiple <HReg/> elements -->
</Coils>
</code>

The **Coils** element is responsible for defining the two-state outputs of a **Coils** type device with MODBUS RTU communication, which will be available for the **ibvunit** program.

The element can contain multiple [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<Coil>|<Coil>]] elements or none at all.

The element contains attributes:

  * **SetMode** - (mandatory) The attribute value determines whether to use the MODBUS ForceSingleCoil or WriteMultipleCoils function  to set the value of a given register. The attribute can take values:
    * **Multiple** - means that communication with the MODBUS device allows for bulk writes for Holding Registers. The **Multiple** value should only be set for MODBUS devices correctly implementing the WriteMultipleCoils function (code 15).
    * **Single** - means that communication with the MODBUS device only allows for single writes for Holding Registers. The Single value should only be set for MODBUS devices correctly implementing the ForceSingleCoil function (code 5).

If the device supports both modes, it is recommended to use **Multiple** for performance reasons.

Each device supporting Coils type variables must correctly implement at least one of the above functions in order to change the two-state output data.

Two-state output reading is performed by the MODBUS ReadCoilStatus function (code 1), which must also be supported by the device.

==== <Coil>====

An element located in the [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<Coils>|<Coils>]] element. The element is responsible for defining a single two-state output of the **Coils** type with MODBUS RTU communication.

<code>
<Coil Addr="0" Name="coil.filter" Rd="1" Wr="1" Min="0" Max="1"/>
</code>

The element contains attributes:

  * **Addr** – the address of the register in a MODBUS RTU compatible device.
  * **Name** – the name of the register. Under this name, the register will function as a variable in the **ibvunit** program and throughout the **IB-System**. The name of the parameter is arbitrary, but it is assumed to be intuitive. Therefore, standardizing names according to the [[en:ibprotocol:start|ibprotocol]] documentation is recommended.
  * **Rd** – a flag (value 0 or 1) indicating whether the register can be read.
  * **Wr** – a flag (value 0 or 1) indicating whether the register can be written to.
  * **Min** – the minimum value for the register.
  * **Max** – the maximum value for the register.

===== <DiscreteInputs> =====

<code>
<DiscreteInputs>
  <!-- multiple <DInput/> elements -->
</DiscreteInputs>
</code>

The **DiscreteInputs** element is responsible for defining the two-state inputs of a **Discrete Inputs** type device with MODBUS RTU communication, which will be available for the **ibvunit** program.

The element can contain multiple [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<DInput>|<DInput>]] elements or none at all.

Each device supporting **DiscreteInputs** type variables must correctly implement the MODBUS ReadInputStatus function (code 2) in order to read the value of a given two-state input.

**DiscreteInputs** type registers are read-only.

==== <DInput>====

An element located in the [[en:ibvunit:ibvunit-dev-modbus-rtu-config#<DiscreteInputs>|<DiscreteInputs>]] element. The element is responsible for defining a single two-state input of the **Discrete Inputs** type with MODBUS RTU communication.

<code>
<DInput Addr="0" Name="disc.gwc.on"/>
</code>

The element contains attributes:

  * **Addr** – the address of the register in a MODBUS RTU compatible device.
  * **Name** – the name of the register. Under this name, the register will function as a variable in the **ibvunit** program and throughout the **IB-System**. The name of the parameter is arbitrary, but it is assumed to be intuitive. Therefore, standardizing names according to the [[en:ibprotocol:start|ibprotocol]] documentation is recommended.
  * **Rd** – a flag (value 0 or 1) indicating whether the register can be read.