XML for the Modbus device

This section describes the XML tags and their attributes that is used to create vendor specific XML files. Once you have created the XML file, you will be able to upload and deploy the XML file using the Workbench. Each vendor XML file must begin with the following process instruction:

<?xml version="1.0" encoding="UTF-8"?>

DeviceDefinition tag

The opening DeviceDefinition tag and its matching end tag surround all other tags within the vendor specific XML file.

<DeviceDefinition name="Tyco Integra C Series Power Meter" type="54" type_name="ModBus">

The DeviceDefinition tag contain these attributes:

Attribute name	Description
Name=	An attribute that specifies the name of the device. The device name will appear in the Device window in the Type parameter. For this example, the device named Tyco Integra C Series Power Meter will appear under the Modbus category.
type_name=	This attribute specifies the device category the XML file will be associated with on the Device window in the Type parameter
type=	This attribute is used by the driver to register a specific device within the node. The value of type= must be unique within the node. You will be safe using a value greater than 500000.

Properties tag

The Properties tag is a section tag that must contain at least one or more Property tags.  A section name and its matching end tag surround all other tags within the section.

<?xml version="1.0" encoding="UTF-8"?>
<Properties>
   <Property name="Variables">
      <Variables>
         <VariableInfo />
         <VariableInfo />
      </Variables>
   </Property>
   <Property name="Structures">
      <Structures>
         <StructureInfo />
         <StructureInfo />
      </Structures>
   </Property>
</Properties>

The following describes each of the XML tags associated with the Properties tag.

Property tag

Each Property tag must contain a Variables tag which in turn must contain a set of VariableInfo tags. The Property tag has one attribute, name=.  The value of the name= attribute can be either Variables or Structures. However, the XML must have at least one Property tag with a name= attribute value of Variables.

Variables tag

The Variables tag is an opening section tag. Within the Variables tag is one or more VariableInfo tags. 

VariableInfo tag

The VariableInfo tag provides the detailed description of the Modbus data region being represented by an individual variable. These items will appear on the Workbench > Devices > Variables tab.

Using the VariableInfo tag, you can represent a variable as a stand-alone item or as a member within a defined structure. The items can be referenced in a trigger action and trigger event. A stand-alone item can be a data type such as INT2, FLOAT4, or STRING. A variable might also have a data type value of STRUCT, in which case a Property tag with a name= attribute value of Structure is needed to define the layout of the structure variable.

To summarize, there must be at least one Property tag in the XML to define the Modbus data registers that will be mapped to device variables. The required Property tag must have a name= attribute with a value of Variables. Additional Property tags with a name= attribute value of Structures are needed if one of the VariableInfo tags within the Variables tag has a data type value of STRUCT.

Sample XML - stand-alone variables

The following sample XML demonstrates how to represent a register or a group of registers in a Modbus data block as stand-alone variable items. The Property tag contains a Variables tag, which in turn contains a collection of VariableInfo tags that define the various variables this device will create. The VariableInfo tags also contain the definition that maps a Modbus data block register to a stand-alone variable.

<?xml version="1.0" encoding="UTF-8"?>
<Properties>
   <Property name="Variables">
      <Variables>
         <VariableInfo name="Coil I/O" type="BOOL" data_table="Coils" options="3" offset="0" xdim="32" />
         <VariableInfo name="AnalogInputsAD" data_table="Holding Registers" offset="0" options="1" type="INT2" xdim="8" />
         <VariableInfo name="AnalogInputs" data_table="Holding Registers" offset="1000" options="1" type="FLOAT4" xdim="8" desc="Analog Inputs" />
         <VariableInfo name="AnalogInput1Mode" data_table="Holding Registers" offset="8001" options="3" type="INT2" desc="Analog Input 1 Mode" />
         <VariableInfo name="AnalogInput1Slope" data_table="Holding Registers" offset="8002" options="3" type="FLOAT4" desc="Analog Input 1 Slope" />
         <VariableInfo name="AnalogInputConfig" data_table="Holding Registers" offset="8100" options="1" type="INT2" desc="Analog Input Configuration" />
         <VariableInfo name="RmtAnn Sensor Ready Data" data_table="Holding Registers" offset="9" options="3" type="INT2" desc="Alarm/Status (0/1) - H9/1 hibyte" />
         <VariableInfo name="RmtAnn Dummy Byte2 Data" data_table="Holding Registers" offset="9" options="3" type="INT2" desc="Alarm/Status (0/1) - H99/1 lobyte" />
         <VariableInfo name="Product Version" data_table="Holding Registers" offset="32" options="3" type="STRING" length="64" desc="Text Data - H32 STRING64" />
         <VariableInfo name="Version Date" data_table="Holding Registers" offset="64" options="3" type="STRING" length="64" desc="Text Data - H64 STRING64" />
         <VariableInfo name="GenLink Min Version" data_table="Holding Registers" offset="96" options="3" type="STRING" length="64" desc="Text Data - H96 STRING64" />
      </Variables>
   </Property>
</Properties>

For the sample XML shown:

• The stand-alone variables will be mapped to the Holding Registers data region, so it is not necessary to use a 40000 – n numbering system for the offset value.

• The offset value is the index location within the data region. In this example 8001 is the equivalent of what a vendor’s data sheet might document as 48001 or 48002 if they use a 1 based numbering system.

The following shows how the VariableInfo tag descriptions are translated into variables that will appear on the Variables tab once the Modbus device is started.

Rather than creating variables for the entire Holding Registers data region as is done when a generic Modbus Device type is created, this sample XML displays only the areas of the data region that you are interested in. The Coil I/O variable represents 32-bits in the Modbus coils data region, which might be a small subset of the entire coils data block. The first 8 Holding Registers on the Modbus device are mapped to a device variable named AnalogInputsAD, while the 8 Holding Registers beginning at offset 8001 are mapped to a device variable named AnalogInput1Mode.

Sample XML - variables within a defined structure

A defined structure is simply a collection of device variables. The following sample XML represents a variable within the device as a member within a defined structure.

<?xml version="1.0" encoding="UTF-8"?>
<Properties>
   <Property name="Variables">
      <Variables>
         <VariableInfo type="STRUCT" name="Data" struct_id="1" />
         <VariableInfo type="STRUCT" name="Setup" struct_id="2" />
      </Variables>
   </Property>
   <Property name="Structures">
      <Structures>
         <StructureInfo name="Live Data Values" struct_id="1" data_table="Input Registers">
            <VariableInfo type="FLOAT4" name="Volts 1" data_table="Input Registers" desc="Voltage #1 (L1-N2/4W or L1-L2 3W)" options="1" offset="0" />
            <VariableInfo type="FLOAT4" name="Volts 2" data_table="Input Registers" desc="Voltage #2 (L2-N2/4W or L2-L3 3W)" options="1" offset="2" />
            <VariableInfo type="FLOAT4" name="Volts 3" data_table="Input Registers" desc="Voltage #3 (L3-N2/4W or L3-L1 3W)" options="1" offset="4" />
            <VariableInfo type="INT4" name="Current 1" data_table="Input Registers" desc="Current #1 (Amps)" options="1" offset="6" />
            <VariableInfo type="INT4" name="Current 2" data_table="Input Registers" desc="Current #2 (Amps)" options="1" offset="8" />
            <VariableInfo type="INT4" name="Current 3" data_table="Input Registers" desc="Current #3 (Amps)" options="1" offset="10" />
         </StructureInfo>
         <StructureInfo name="Configuration Setup Parameters" struct_id="2" data_table="Holding Registers">
            <VariableInfo type="INT2" name="Demand Time" data_table="Holding Registers" desc="Demand Time Minutes, Reset (0 Only)" options="3" offset="0" />
            <VariableInfo type="INT2" name="Demand Period" data_table="Holding Registers" desc="Demand Period (Minutes) 8,15,20,30,60" options="3" offset="2" />
            <VariableInfo type="FLOAT4" name="System Voltage" data_table="Holding Registers" desc="System Voltage (Volts) 1V - 400kV" options="3" offset="6" />
            <VariableInfo type="INT4" name="System Current" data_table="Holding Registers" desc="System Current (Amps) 1-9999" options="3" offset="8" />
         </StructureInfo>
      </Structures>
   </Property>
</Properties>

The sample XML demonstrates how to represent a group of Modbus data registers as a device structure variable.

• The first Property tag contains the name="Variables" attribute.
•  Next, the Variables tag has two VariableInfo tags both defined with a type of STRUCT. There is also an attribute named struct_id= that will be used as a link to the actual definition of the structure in the second Property tag with the value of Structures. 

Notice the second Property tag.

• This Property tag contains the name="Structures" attribute. The Structures tag provides the details of the two VariableInfo tags defined within the first Property tag (name="Variables"). 
• The StructureInfo tag associates the Modbus data register with the device variables that are going to be defined within the structure. For example, the StructureInfo tag named Live Data Values is associated with the Modbus Input Registers data block, while the Configuration Setup Parameters represents the Holding Registers data block. Again, the VariableInfo tag is used to describe the data elements that comprise the structure. Notice also that the structure contains a mix of different data types to accurately describe the data mapping within the Modbus device. The VariableInfo tag must also have a data_table attribute that identifies the register that the variable belongs to. This register value must match the register value defined in the StructureInfo tag.

The following shows how the previous Variables tag description, combined with the Structures tag description, are translated into device variables.

The two STRUCT items defined in the Variables tag are now device structure variables. The elements within the structure are the VariableInfo tags defined within the StructInfo tags.

VariableInfo attributes

The VariableInfo tag is the element within the vendor specific XML file that describes the characteristics of the variable as it is represented in the device.

Sample XML

The sample XML show the various attributes that are defined with the VariableInfo  tag. Each attribute is broken down to highlight its use and any special values that the attribute requires.

Attribute descriptions

Attribute name	Description
name=	This is the descriptive name that the device will associate with the data register location being mapped. Example: name="Coil I/O" As it will appear on the Variables tab:
type=	This is the data type that corresponds to how the Modbus device represents the data at the specific register location. Coil and Discrete input data regions – These regions use the Modbus bit data type. The corresponding data type is BOOL. Input register or Holding registers – Each element in these regions store data within a 16-bit word. The corresponding data type is an INT2 or a UINT2, the use of which depends upon whether the Input or Holding registers allow signed (negative) numbers. Many vendors group contiguous element address to form a 32-bit double word, capable of holding very large numbers. The corresponding data types for this configuration are INT4 (signed numbers), UINT4 (unsigned numbers), and FLOAT4 (floating point) numbers. Example: type="FLOAT4" As it will appear on the Variables tab:
options=	A value of 1 indicates the variable can only be read (read only). A value of 3 indicates the value is readable and writable (read/write). Example: options="3" As it will appears on the Variables tab: If you right-click on the variable, a pop-up menu will be provided where the user can read the value of the variable or change its value.
offset=	This value indicates the location of the element in the data region. Be aware that many of the Modbus device vendors number their elements from 1 – n in their documentation, but use a 0 – n numbering system in the actual mapping on the device. It is suggested that you use the vendor’s documented offset when mapping the element to the offset value in the XML. Be prepared to modify this value by subtracting 1 from the documented element location if you do not read the value that you are anticipating. Many of the Modbus vendors use a register numbering system in which the address for the Coil registers are numbered from 0 – 9999, the Discrete input data regions s are numbered from 10000 – 19999, Input registers are numbered from 30000 – 39999, and the Holding registers are numbered from 40000 – 49999. The value used in the offset parameter does not use this addressing scheme. It simply uses a value from 0 - n. Example: offset="2"
xdim=	Optional. This attribute is used to specify the size of an array of elements. The VariableInfo tag with the name attribute value of AnalogInputs in the XML example shown above has an xdim value of 8. The driver will create a variable named AnalogInputs as an array of eight FLOAT4 variables. These device variables are mapped to the Modbus device’s Holding registers data region, beginning at element offset 1000. The data held in these elements are 4-byte Floating point values which means two registers are needed to hold each value. Consequently, this device variable is mapped to elements 1000 – 1016 in the Modbus device’s Holding registers area. Example: xdim="8"
data_table=	This attribute is used when defining a stand-alone variable. It identifies the Modbus data register the variable is mapped to. This attribute is used in the StructureInfo tag when defining device variables within a structure. Example: data_table="Holding Registers"
desc=	Optional.  A textual description that will be shown with the variable on the Workbench > Devices > Variables tab. Example: desc="Analog Inputs" As it will appear on the Variables tab:
data_conversion	A conversion operation that is performed on the data after it is read from the Modbus device. This feature is implemented in version 2.5 of the Modbus driver.
bitno	The bitno allows you to access a specific bit. The corresponding data type is BOOL. Holding registers – Each element in these regions store data within a 16-bit word. The corresponding data type is an INT2 or a UINT2, the use of which depends upon whether the Holding registers allow signed (negative) numbers. <?xml version="1.0" encoding="UTF-8"?> <Properties> <Property name="Variables"> <Variables> <VariableInfo name="Devpower" data_table="Holding Register" offset="0" options="3" bitno="0" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="PLC power" data_table="Holding Register" offset="0" options="3" bitno="1" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="Rack power" data_table="Holding Register" offset="0" options="3" bitno="2" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="switch" data_table="Holding Register" offset="0" options="3" bitno="3" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="hub" data_table="Holding Register" offset="0" options="3" bitno="4" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="serverpower" data_table="Holding Register" offset="0" options="3" bitno="5" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="PLC2power" data_table="Holding Register" offset="0" options="3" bitno="6" type="BOOL" desc="Sample variable to test"/> <VariableInfo name="PLC3power" data_table="Holding Register" offset="0" options="3" bitno="7" type="BOOL" desc="Sample variable to test"/> </Variables> </Property> </Properties> </DeviceDefinition> Limitations of Nested Bool: xdim cannot be used with bitno as you will not be able to define the array of nested bits.
length	The length is used only for the variables of type STRING.

Data conversion

Following are the new values for the data_conversion attribute and examples of how the data will be converted.

Word (2 byte) and Double Word (4 byte) integer data conversion

The wordswap data conversion keyword is used with INT4, UINT4, and FLOAT4 data types. It will be ignored if used with INT2, UINT2, or BOOL data types.

FLOAT4 works only with wordswap.

The byteswap variables will be both readable and writable.

 The hi, lo, hihi, and lolo variables will be read only. These variables cannot be writable because the Modbus protocol does not provide the means to write a single byte within a register or double register.

Scaling factor

The Scaling factor is a number the value is divided by after the data conversion. Scaling factor works for all the data conversions except for the byteswap. Following is an example of an XML using the Scaling factor:

<?xml version="1.0" encoding="UTF-8"?>
    <Properties>
        <Property name="Variables">
            <Variables>
                <VariableInfo name="Holding0_FLOAT4" data_table="Holding Registers" offset="0" options="3" xdim="10" data_conversion="wordswap" scaling_factor="10" type="FLOAT4" desc="Holding Register 0 - FLOAT4 - offset 0 wordswap"/>
                <VariableInfo name="Holding0_INT4" data_table="Holding Registers" offset="0" options="3" xdim="10" data_conversion="wordswap" scaling_factor="100" type="INT4" desc="Holding Register 0 - INT4 - offset 0 wordswap"/>
                <VariableInfo name="Holding0_INT2" data_table="Holding Registers" offset="0" options="3" xdim="10" data_conversion="hibyte" scaling_factor="5" type="INT2" desc="Holding Register 0 - INT2 - offset 0 hibyte"/>
            </Variables>
        </Property>
    </Properties>
</DeviceDefinition>

Continue to Deploying the XML file.