MT Data Provider

Copyright (c) 2002 - 2014 Inventia

Version: 2.11.x
Last change: 24/Sep/14
Created: 31/May/04

Introduction:
The Program works as an OPC, ODBC and CSV server, serving resources of Telemetry (MT)
modules, as well for reading and writing, as for unsolicited messaging.
The program works as an application as well as a system service.
Diagram of server functionality:

Installation procedure:
Before installing a new version one has to be sure that program is not running.
The Program is delivered as an executable file that installs it and registers in the operating
systems register database. Uninstalling of the program is a standard Windows routine.
One can place the program in any directory and register it manually in the system by issuing
the command:
mt_opc.exe /regserver
or as a system service:
mt_opc.exe /regservice
or unregister it:
mt_opc.exe /unregserver
mt_opc.exe /unregservice
The program requires the NDIServer.dll file in order to run (installed with the program as
standard).

Configuration:
The Configuration of the server is written in the XML file.
An example of the configuration:
<?xml version="1.0"?>
<opc>
<configure net_mode="static" udp_port="7110" timestamp="system"
csv_log="true" csv_path="C:\" odbc_log="false"
odbc_source="myodbc" odbc_user="" odbc_password=""
odbc_write="1" log_filter="false" aliases="false"
debug_file_type="one_log" restore="false" backup_time="5"
updateable="false" debug="false"/>
<network name="device" ip_receiver="10.10.32.4"
udp_port="7110" ip_header_receiver="10.10.32.4"
ip_header_sender="10.10.32.1" timeout="12" retries="3"
module_type="mt101" update="false" add_crc="true"
csv_msg_log="true" odbc_msg_log="true" dreg_order="hi_lo"
expire_time="0" debug="false" enable="true">
<modbus name="slave" id="1" type="binary_inputs" address="0"
size="16" interval="120" csv_data_log="false"
odbc_data_log="false" debug="false" enable="true"/>
<modbus name="slave" id="1" type="binary_outputs" address="0"
size="60" interval="60" start="7:20:00" stop="19:45:00"
debug="false" enable="true"/>
<modbus name="slave" id="1" type="registers" address="0"
size="4" interval="180" start="6:35:00" stop="14:40:30"
day_of_week="1010100" debug="false" enable="true"/>
<modbus name="slave" id="1" type="registers" address="0"
size="64" format="bool" interval="180" debug="false"
enable="true"/>

<modbus name="slave" id="1" type="analog_inputs" address="0"

size="16" interval="120" debug="false" enable="true"/>
<modbus name="slave" id="1" type="analog_inputs" address="0"
size="8" format="float4" interval="120" debug="false"
enable="true"/>
</network>
</opc>
All information for the server must exist within <opc> tags.
Within <opc> tags there are two other types of tags: <configure> and <network>.
Global settings for the server are written within <configure> section.

<configure> section input arguments

<net_mode> - servers modus operandi (mode static or dynamic)
"static" the server works in direct communication with modules (static IP addresses)
Notice:
This is a default mode for configuration where the server and modules can see each other,
that means they can communicate directly and know each others IP addresses. This is a case
when both the server and modules have static, public addresses or operate in the same APN.
Configuration:
In this mode fields <ip_receiver> and "<ip_header_receiver> have the same IP address.
In the <ip_header_sender> field we find the IP address of the machine the server is running
on.
"dynamic" the program works with direct connection to the APN (at least in one way), with
modules with no static IP Addresses.
Notice:
In this mode called dynamic, the program communicates with modules not by IP addresses,
but by their serial numbers. This is the only way to communicate with units provided with
dynamically assigned IP addresses. This mode may be employed in systems where the IP
address is static and known.
The advantage is that a change of the SIM card does not force any changes in configuration
neither for the module nor the server.
The disadvantage is that remote configuration of the module is impossible.
This mode may be employed in communication with units belonging to partially closed
APNs with no access from the outside (typical public APNs).
The server does not query in the beginning since it does not know the IP address of the unit
to query.
Upon arrival of the data from the module (the module in proxy mode tries to log on to proxy
server) the server gets the actual address and starts querying for data.
Configuration:
In this mode in the <ip_header_receiver> field we fill the modules serial number.
That is all.
The values of <ip_receiver>and <udp_port> fields are unknown, and therefore they can be
empty.
Their contend shall not be taken into consideration.
The <ip_header_sender> field can be omitted as well, since default address for proxy server is
255.255.255.255. This number must be filled in the modules configuration in the number list.

The parameter <csv_path> - defines the path to the catalog where CSV files shall be stored
(default- "C:\")
The <csv_log> parameter decides whether any data is going to be written into the CSV files.
The (default value) true - permits writing data into the CSV files; event triggered data from
devices not defined in this configuration file will be written together with their IP address.
false no data arriving to the server, regardless of any other settings, will be written into
CSV files.
<udp_port> - the port the server is listening (default "7110")
<timestamp> - date time stamp for current data:
"system" = system time at the moment of data reception,
"data" = date stamped on the data (currently applicable to event data)
For data from datalogger, system setting convert UTC timestamp to local time.
<debug> - "true" record of all communication with the server, "false" (default value)
<debug_path> - defines the path to the folder where log files shall be stored ( - current)
<debug_file_type> - "one_log" (default), the log is recorded in one growing file. With value
"daily_log" the file name comprises current date so the log keeps daily records.
<config_path> - defines the path to the folder where configuration files (mt_aliases,
mt_log_filter) shall be stored ( - current)
<dreg_order> - defines register sequence In 2 register values. Accepted values are "hi_lo"
(default) and "lo_hi". It's global value, valid if not locally defined in <network> section.
<odbc_log> - cooperation with database via ODBC connection, "true"(default) or "false"
<db_type> - defines database type. Available settings are mssql (default), postgresql,
mysql.
<odbc_source> -system ODBC connection name
<odbc_user> - database username (optional, where required)
<odbc_password> - password (optional, where required)

<odbc_crypted_password> - parameter set by MTManager OPC configuration module.

Defines ODBC password (optional) in encrypted format. It makes <odbc_password>
obsolete.
<odbc_error> - defines program's behaviour when database error is appeared; "retry" restarting database connection and trying to insert data again after pushing data record at the
end of queue (default behaviour), "ignore_all" ignoring all errors
<odbc_millisec> - true makes timestamp accurate to milliseconds (default is to seconds)
<odbc_write> - interval of checks the opc server does to mt_write table looking for a new
value to set; 0 switches the check off (default)
<log_filter> - filtering of variables - true. The list of variables to be written into CSV file or
to ODBC database has to be defined in mt_log_filter file (the mt_items.log file can be
used in registering all variables to create the filter definition file). Default value is false.
<aliases> - starts servicing of aliasing feature for names - true. Default value is false.
Aliasy are defined in mt_aliases file, by inserting variables names , a comma or semicolon
and the alias, for instance. mt101id1.REG4,Absolute pressure.
<restore> - when set to true, makes the program restart in the same state it was at shut
down. All the OPC variables will be restored to previous values including the timestamp and
last read time values (late is valid until the computer is shut down). Default value is false.
<backup_time> - defines interval of registering the state (default is1 s)
<updateable> - this parameter activates changes made by update variable(from
<network>section) in some of the global settings in configuration (<configure> section).
Default value is false.
<opc_log> - parameter decides whether OPC interface is active or not. Default value is
true.
<watch_dog_time> this parameter defines the wait time for non responsive thread (in
seconds). After this time the program shuts down.
Default value 0 disables the watchdog. (The program may be restarted by system recover
function or by ModDog program).

<decimal_symbol> - defines sign which separates fracture part of floating point value from
integer part. Default setting is . (dot).
<scientific_notation> - parameter allows user to select notation of floating point values
between decimal and scientific. Default setting is false floating point values are written in
decimal notation.
<csv_separator> - defines sign which separates columns in CSV files. Default setting is ;
(semicolon).
<csv_millisec> - true makes timestamp accurate to milliseconds (default is to seconds)
<tag_separator> - defines sign (or signs), separates master's name from slave's name within
tag. Default setting is --.

<network> section input arguments

Tags <network> define single MT unit in the APN.
Following arguments are allowed:
<name> - any unit name (should be unique default value is IP address)
<ip_receiver> -the IP address data frames shall be sent to
<udp_port> - the UDP port data frames shall be sent to
<ip_header_receiver> - modules IP (in net_mode="0" same as <ip_receiver>)
<ip_header_sender> - senders IP (in net_mode="1" insignificant)
<timeout> - transmission timeout in seconds
<retries> - number of retries (at timeout)
<add_crc> - "true" for Modbus mode, in firmware versions 1.31 or later, "false" - else (default
value)
<module_type> - "mt101" (default value), mt301, mt302, mt702, mt703 itc. Generally defining
module type is not required, except when the status sent on event by mt101 and mt301/302 modules is
used. (Replaces old parameter <unsolicited_status>, kept to support legacy)
<csv_msg_log> - true all events will be recorded in the CSV files, logger - only events with the
logger will be recorded, false no events will be recorded (default value).

<odbc_msg_log> - logs all events into database via ODBC - "true", logger only events
with logger, "false" (default)- no logging performed.
<odbc_read_table> - name of the table for read values (optional, where different from default
mt_read)
<odbc_logger_table> - name of the table recording events from the logger (optional, where
different from default mt_logger)
<update> - true defines a variable available both from the OPC server and from the
database used to communicate with the server in order to carry out an action on the device or

to change some configuration elements. (See detailed description in comments on update

variable).
The name of this variable consists of the device name and update (after the period) e.g.
"device.update". The default value is false.
<expire_time> - in seconds. After defined time the value of the record is signed BAD. If the
record is updated before defined time the timer restarts counting. The default value is "0" and
means infinite time.
<dreg_order> - defines register sequence In 2 register values. Accepted values are "hi_lo"
(default) and "lo_hi".
<active> - the parameter defines OPC variable indicating the time of activity of the module
defined in <network>. The value of the variable represents the time elapsed since reception of
the last data frame send from the device. The parameter takes following values: "false"
(parameter is inactive - default setting), "sec" (time in seconds), "min" (time in minutes),
"hour" (time in hours).
<buf_log_res> - this parameter, along with buf_log_addr, secures correct data reception send
from program data loggers that can be created on MT-10X, MT-202. This parameter describes
logger record structure in a form of a string of zeroes, ones and twos, which correspond
accordingly to 16 and 32-bit integer values and 32-bit floating point values. User can define
up to 32 16-bit values. For example, buf_log_res = "110002" means the record of logger
consists of two of 32-bit values, three 16-bit values, and finally 32-bit floating point value.
Each record is preceded by a time stamp consisting of a six registers: seconds, minutes, hour,
day of month, month and year (each in a separate register). The first record of the recorder
should be located at the address defined by buf_log_addr. If buffer_log_res is empty program
data logger servicing is off.
<buf_log_addr> - address of first data logger record. All unsolicited messages
containing this register and higher will be processed as data logger. Program
data logger servicing is also controlled by buf_log_res parameter.
<debug> - "true" for recording of communication log on <network> level (without
confirmation frames and unsolicited messages), "false" (default value)
<enable> - the tag is active/inactive "true"/"false" (default "true")
Within <network> tags there are <modbus> tags.

<modbus> section input arguments

<modbus> tag defines specific single query for resource.
Following parameters are allowed:
<name> - name of the resource or slave unit connected to MT module
<id> - modbus ID of MT module or slave unit connected to MT module
<type> - resource type ("binary_inputs", "binary_outputs", "analog_inputs", "registers")
<format> - data format for registers and analog inputs ("int2", "long4", "float4", "bool");
"int2" is a default format, "long4" and "float4" consist of two "int2" where "int2" consists of 16
"Boolean values". For binary inputs and outputs format doesn't affect.
<signed> - if false (default value) data is treated as values without sign (0 to 65535 for 16-bit
and 0 to 4294967295 for 32-bit). If set to true value is presented with sign (-32768 to 32 767 for
16-bit and -2147483648 to 2147483647 for 32-bit).
<address> - modbus-address of the resource
<size> - memory space size to be read (depends of the data format)
<block> - the parameter defines additional tag which contains all registers from modbus
section and present them as one value. Block can be in "ascii" type, "hex" type or not used
"false" (default).
First one presents lower bytes from registers as text string (or '_' if character is not printable).
Special characters can be use while writing: \n new line (character's value 10), \r carriage
return (13), \t horizontal tab, \0 zero, \\ - '\' character.
Second type of block ("hex") presents value of registers as hexadecimal values, eg
'00010002FFFF0004' it's 4 registers with values 1,2,65535,4 in successive registers.
The tag's format is as follow: BREGA<addres>:<size> (eg deviceslave.BREGA4:16) for "ascii"
type and BREGH<addres>:<size> when"hex" is selected.
<interval> - polling interval (in seconds). If 0 - no polling is performed
<start> - polling start (format hh:mm:ss)
<stop> - polling end (format hh:mm:ss)

<day_of_week> - this parameter defines week days to perform polling

1 means polling is done this day, while 0 means no polling this day
The mask defined in this 7 characters parameter starts at Monday and every next position
corresponds to next week day. For instance 1010100 means reading data at Monday,
Wednesday and Friday.
<csv_data_log> - true each data frame will be recorded in the CSV file, false - (default
value) none of the arriving data will be recorded.
<odbc_data_log> - data jogging into database via ODBC, "true" or "false" (default)
<debug> = "true" - for recording of communication log on the resource level (without
confirmation frames), "false" (default value)
<enable> - the tag is active/inactive "true"/"false" (default "true")

Start of the program:

Program is started by a command specifying the name of configuration file *.xml:
mt_opc.exe sample.xml
As a default the program starts and runs in the background.
To start the program in visible mode type the command with "/show" parameter.
mt_opc.exe /show sample.xml
If the configuration *.xml file parameter is not supplied, the server tries to read the file name
from the startfile". Should it not find the "startfile", it assumes that it is a "sample.xml" file.
This method allows any OPC client to start the server automatically.
When the starfile points to a well defined *.xml file it is enough to start the server with the
command:
mt_opc.exe
or, in visible mode,
mt_opc.exe /show

Comments to data formats:

Variables of register and analog_inputs type may be presented in following formats:
int2 (16 bit, native), int4 (32 bit) consisting of 2 registers, float4 (32 bit) and bool (16
bits in a register).
Now the variables can be presented simultaneously in many formats.
Defining a variable in many formats does not force multiple readings for each defined format.
It is enough to set the reading interval for one format, leaving the rest of them with interval 0.
Variables of register type can be written in any format. One has however to be aware of that
setting a bit in Boolean format the program shall when setting the bit take into
consideration the last read value of the whole register and after setting shall send a new value
of the register. This means that when we want to set more than one bit of the register we have
to wait for the first bit settles before we set another one. Otherwise this bit will be set with
the old value.
In case of values consisting of 2 registers, the sequence of register may be significant. To
handle this, the variable dreg_order, was introduced. In most cases it should stay at its
default value hi_lo. Reverse order is produced by setting it to lo_hi.

Comments to database cooperation:

The cooperation with database employs ODBC interface as a mid layer between the server
and database. For that purpose one has to create an empty database and define the ODBC
source connected to it.
ODBC interface allows employing any database. Confirmed and tested databases are MySQL,
Microsoft SQL, Microsoft Access and MSDE.
Should server fail to connect to database, the log file will show ODBC connect failure" entry
and the server will continue working without database connection.
The server will write all received (scheduled or on event) values with their names,
timestamps and data quality into mt_read table (or other user defined), provided it is
configured to do so.
The mt_read table consists of 4 columns with variable name, value, timestamp and status.
Notice that the value is written as varchar type.
The mt_logger table (or other user defined) recording events from the logger has identical
format.
Writing the variable name and new value into mt_write table results is changing this value
in the addressed module. Values can be inserted manually or by SQL query: "insert into
write_to_mt values ('device--slave.REG15', '123'); "insert into write_to_mt values ('device-slave.REGF8', '123.456'); "insert into write_to_mt values ('device--slave.REGB2:4', '1'); "insert
into write_to_mt values ('device--slave.BO6', '0')
As we can see writing and reading goes for different data formats like float4, long4, bool.
When the device sends a variable in multiple formats they are recorded in every defined
format separately.

Comments to writing into CSV files:

Server allows writing data from the logger and from event triggered transmissions and
scheduled readings into CSV files. CSV files recording events carry names starting with
acronym msg, logger files with log, and data files with data.
CSV files support data formats (int2, float4, long4 and bool). If the variable is defined
in multiple formats CSV file will record each format separately.

Operating in interactive and on event modes:

The server works according to schedule defined by, days of week, starting and ending hours
and intervals.
The system can be configured to query rarely or not query at all, waiting only for event
triggered transmissions.
Should the user wish to see the current state of the device, the variable update in <network>
section comes to use. Setting update to true generates for this <network> section a
variable name_of_network.update. Supplying a value to this variable from an OPC client
or database forces reading of all values defined in <network> section or execution of other
actions.

Comments on update variable:

This variable communicates to the server a type of action to be performed on the device or
change of configuration settings regarding this device.
Specific action is achieved by setting a value representing a command for MT Data Provider.

Perform all actions for selected <network>

Perform actions with interval different than 0

Perform actions with interval equal to 0

11 Switch querying off for the <network>

12 Switch querying back on for the <network>
21 Start device logging
22 Stop device logging
31 Set csv_msg_log variable to true
32 Set csv_msg_log variable to false
33 Set csv_msg_log variable to logger
41 Set all csv_data_log variables to true
42 Set all csv_data_log variables to false
43 Reset all csv_data_log variables to previous values
51 Set odbc_msg_log variable to true
52 Set odbc_msg_log variable to false
53 Set odbc_msg_log variable to logger
61 Set all odbc_data_log variables to true
62 Set all odbc_data_log variables to false
63 Reset all odbc_data_log variables to previous values
In a similar way, the update variable may alter global settings for the program
(provided the updateable parameter in <configure> section allows it).
This requires 2 codes. First we enter 255,to mark that we want to alter global settings and
subsequently one of following values defining intended alteration:
255 Switch to command mode

11 Set the restore variable true

12 Set the restore variable false
21 Set the debug variable true
22 Set the debug variable false
31 Set the csv_log variable true
32 Set the csv_log variable false
41 Set the "log_filter" variable true
42 Set the "log_filter"variable false
51 Set the odbc_log variable true
52 Set the odbc_log variable false
100 Dump internal log to file
101 Shutdown a MTDP process
All alterations made in this way have influence only on running instance not on configuration
defined in XML file.
After restart of the program the settings defined in XML file will be applied.

Requirements:
- A computer with installed MS Windows XP/ Server 2003 or 2008/ Vista/ 7/ 8 (the latest
service packs are required).
- The access to Internet or to an APN.