viaConnector
============
The viaConnector is a Software to gather data from machines and redirect them.
As an example the viaConnector can act as a mmJson server, to gather
machinemonitoring-events and write them in database used by the Weinig App
Suite. In general the viaConnector isn't limited to mmJson, machinemonitoring
or the database of the Weinig App Suite.

Architecture
------------
The viaConnector can be extendet through plug-ins. These plug-ins are seperated
in source and target plug-ins. Source plug-ins are for getting data from
machines like for example mmJson, which is able to get machinemonitoring-events
or WPP. Target plug-ins control to which point the data is redirected. Examples
for a target plug-ins are the database of the Weinig App Suite or MindSphere.

Supported platforms
-------------------
For Windows there exists builds.
Linux is supported, but you have to manually build it. 

Source plug-ins
---------------
The description of the plug-ins are in the respective documentation.

At the moment the following sources are supported:
* mmJson
* WPP
* S7
* OPC UA (Woodworking)

At the moment the following targets are supported:
* Weinig App Suite
* Weinig Control Suite
* A integrated OPC UA Server (Woodworking)
* A SQL Database
* A CSV File
* A Server with an REST API
* MindSphere

Command Line Arguments
----------------------
-l Printing legal stuff (licences of libs used) and quit.

Configuration
-------------
The viaConnector uses a ini-File for its configuration. This file is also used
for the configuration of the plug-ins. How the plug-ins are configured is
explained in the respective documentation of the plug-in.

The `viaConnector.ini` file should be located at either the usual folder for
userspecific configuration (`%APPDATA%\Weinig\viaConnector.ini` on Windows) or
in the same folder as the `viaConnector.exe`. If a `viaConnector.ini` exists at
both places the one in the same folder as the exe file will be used.

In the configuration it's possible to disable specific plugins, configure a
proxy server, and logging.

Disabling Plugins
-----------------
Plugins can be disabled in the config file when not needed.
An Example of the ini with the default values

``
[core]
disabledPlugins="ContolSuite"
``

Logging Configuration
---------------------
It's possible to specify the log-level of each module on it's own. This is done
at the log key in the `core` group.  Different log-levels can be seperated with
a `\n`.
The logfile configuration is done in the `logfile` group. By it creates a copy
of the old log on start to prevent ever-growing logfiles. Also when maxSize
(in bytes) is reached, the logfile will be copied to oldcopy and a new logfile
will be started.

Loging Example
--------------
``
[core]
log=*.debug=false\ncore.debug=true

[logfile]
filename="viaConnector.log"
oldcopy="viaConnector.lastlog"
maxSize=52428800
``

Unit Overwriting
----------------
It's possible to overwrite units on maintenance and condition datasets. The
format of the group is `unitOverwrite/<serialno>/<CONDITION/MAINTENANCE>/<ID>`.
Instead of an ID, a wildcard `*` is possible.

Unit Overwriting Example
------------------------
``
[unitOverwrite/10001346/CONDITION/{5440cdd5-b46e-48a9-a4b1-f081f13a9146}]
unitText=Stunden
factor=0.00027777777

[unitOverwrite/123456/MAINTENANCE/*]
unitText=Stunden
factor=0.00027777777
``

XML Overwrite
-------------
It's possible to overwrite arbitary data. This can be configured in an XML file
per machine. To do this, we need to specific the XML file in the
`viaConnector.ini`.

Currently only the field `comment` for Maintenance Definitions is supported.

viaConnector.ini XML Overwrite Example
--------------------------------------
``
[xmlOverwrite/123456]
xml=123456.xml
``

XML Example
-----------
``
<MaintenanceComponents>
    <MaintenanceComponent ID="0">
        <Comment>Kommentar 1</Comment>
    </MaintenanceComponent>
    <MaintenanceComponent ID="1">
        <Comment>Kommentar 2</Comment>
    </MaintenanceComponent>
</MaintenanceComponents>
``


Limiting
--------
The integrated limiter will filter out redundant data (Except state which is
used for keep-alive). It also prevents operating data, condition components and
maintenance components to be updated in too short time. By default it will only
send one update in 30 seconds for these values.

It's possible to change the filtering timespan. The waitTime value is in
milliseconds. The default is 30000.

It's also possible to change to keep-alive timespan. So state will only be
dropped if resend in less then the keep-alive timespan. The default is 10000.
Changing this value is not recommended and can lead to problems.

Limiting Example
----------------
``
[limit]
waitTime=60000
keepAliveTime=60000
``

Running as Service
------------------
On windows a service differs from a normal executable. The windows build of the
viaConnector supports running as service. 

The viaConnector is able both to set-up and to remove itself from the services.
This is done by command line arguments. The following arguments are supported

``
-i(nstall) [account] [password] : Install the service, optionally using given
                                  account and password.
-u(ninstall)    : Uninstall the service.
-e(xec)         : Run as a regular application. This also happens when the
                  viaConnector is started without an argument.
-t(erminate)    : Stop the service.
-v(ersion)      : Print status information if the service is running.
-h(elp)         : Shows info about the command line usage. 
``

Note: To be able to install the service, you need administrator permissions.
Note: When run as service, there is no gui available. The logs need to be
      viewed by the logfile. 
Note: Due to the way windows handles proxy settings (per user). You might need
      to manually specificy the proxy settings for the relevant plugins.
Note: All of this is windows specific. On a unix system you would need to 
      write a init-script/systemd-service (depending on the system) to run
      the viaConnector as daemon. 
